Dark Mode

概览

自动更新原生界面

“本地界面”包括文件选择器、窗口边框、对话框、上下文 菜单等 - 任何UI来自操作系统而非应用的界面。 默认行为是从操作系统选择自动主题。

自动更新您自己的界面

如果您的应用有自己的黑暗模式，您应该在与系统黑暗模式设置同步时切换。 你可以通过 prefers-color-scheme CSS 媒体查询来实现此功能.

手动更新您自己的界面

If you want to manually switch between light/dark modes, you can do this by setting the desired mode in the themeSource property of the nativeTheme module. This property’s value will be propagated to your Renderer process. Any CSS rules related to prefers-color-scheme will be updated accordingly.

macOS 设置

在 macOS 10.14 Mojave 中， Apple 为所有 macOS 电脑引入了一个全新的 系统级暗色模式。 如果您的 Electron 应用具有深色模式，您可以 使用”本机 api” 应用 应用。

In macOS 10.15 Catalina, Apple introduced a new “automatic” dark mode option for all macOS computers. 为了让API isDarkMode 和 Tray 在这个模式中正常工作，你需要在 Info.plist 文件里把 NSRequiresAquaSystemAppearance 设置为 false ，或者使用 >=7.0.0 的Electron。 Both Electron Packager and Electron Forge have a darwinDarkModeSupport option to automate the Info.plist changes during app build time.

If you wish to opt-out while using Electron > 8.0.0, you must set the NSRequiresAquaSystemAppearance key in the Info.plist file to true. Please note that Electron 8.0.0 and above will not let you opt-out of this theming, due to the use of the macOS 10.14 SDK.

示例

此示例演示了Electron 应用程序从nativeTheme中获取主题颜色。 此外，它还使用 IPC 通道提供主题切换和重置控制。

docs/fiddles/features/dark-mode (27.0.1)Open in Fiddle

  • main.js
  • preload.js
  • index.html
  • renderer.js
  • styles.css
  1. const { app, BrowserWindow, ipcMain, nativeTheme } = require('electron')
  2. const path = require('node:path')
  4. function createWindow () {
  5.   const win = new BrowserWindow({
  6.     width: 800,
  7.     height: 600,
  8.     webPreferences: {
  9.       preload: path.join(__dirname, 'preload.js')
  10.     }
  11.   })
  13.   win.loadFile('index.html')
  14. }
  16. ipcMain.handle('dark-mode:toggle', () => {
  17.   if (nativeTheme.shouldUseDarkColors) {
  18.     nativeTheme.themeSource = 'light'
  19.   } else {
  20.     nativeTheme.themeSource = 'dark'
  21.   }
  22.   return nativeTheme.shouldUseDarkColors
  23. })
  25. ipcMain.handle('dark-mode:system', () => {
  26.   nativeTheme.themeSource = 'system'
  27. })
  29. app.whenReady().then(() => {
  30.   createWindow()
  32.   app.on('activate', () => {
  33.     if (BrowserWindow.getAllWindows().length === 0) {
  34.       createWindow()
  35.     }
  36.   })
  37. })
  39. app.on('window-all-closed', () => {
  40.   if (process.platform !== 'darwin') {
  41.     app.quit()
  42.   }
  43. })
  1. const { contextBridge, ipcRenderer } = require('electron')
  3. contextBridge.exposeInMainWorld('darkMode', {
  4.   toggle: () => ipcRenderer.invoke('dark-mode:toggle'),
  5.   system: () => ipcRenderer.invoke('dark-mode:system')
  6. })
  1. <!DOCTYPE html>
  2. <html>
  3. <head>
  4.     <meta charset="UTF-8">
  5.     <title>Hello World!</title>
  6.     <meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline';" />
  7.     <link rel="stylesheet" type="text/css" href="./styles.css">
  8. </head>
  9. <body>
  10.     <h1>Hello World!</h1>
  11.     <p>Current theme source: <strong id="theme-source">System</strong></p>
  13.     <button id="toggle-dark-mode">Toggle Dark Mode</button>
  14.     <button id="reset-to-system">Reset to System Theme</button>
  16.     <script src="renderer.js"></script>
  17.   </body>
  18. </body>
  19. </html>
  1. document.getElementById('toggle-dark-mode').addEventListener('click', async () => {
  2.   const isDarkMode = await window.darkMode.toggle()
  3.   document.getElementById('theme-source').innerHTML = isDarkMode ? 'Dark' : 'Light'
  4. })
  6. document.getElementById('reset-to-system').addEventListener('click', async () => {
  7.   await window.darkMode.system()
  8.   document.getElementById('theme-source').innerHTML = 'System'
  9. })
  1. :root {
  2.   color-scheme: light dark;
  3. }
  5. @media (prefers-color-scheme: dark) {
  6.   body { background: #333; color: white; }
  7. }
  9. @media (prefers-color-scheme: light) {
  10.   body { background: #ddd; color: black; }
  11. }

它是如何工作的呢？

从 index.html 文件开始：

index.html

  1. <!DOCTYPE html>
  2. <html>
  3. <head>
  4.     <meta charset="UTF-8">
  5.     <title>Hello World!</title>
  6.     <meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline';" />
  7.     <link rel="stylesheet" type="text/css" href="./styles.css">
  8. </head>
  9. <body>
  10.     <h1>Hello World!</h1>
  11.     <p>Current theme source: <strong id="theme-source">System</strong></p>
  13.     <button id="toggle-dark-mode">Toggle Dark Mode</button>
  14.     <button id="reset-to-system">Reset to System Theme</button>
  16.     <script src="renderer.js"></script>
  17.   </body>
  18. </body>
  19. </html>

以及 styles.css 文件：

styles.css

  1. @media (prefers-color-scheme: dark) {
  2.   body { background: #333; color: white; }
  3. }
  5. @media (prefers-color-scheme: light) {
  6.   body { background: #ddd; color: black; }
  7. }

该示例渲染一个包含几个元素的 HTML 页面。 <strong id="theme-source"> 元素显示当前选中的主题，两个 <button> 元素是 控件。 CSS 文件使用 prefers-color-scheme 媒体查询 设置 <body> 元素背景和文本颜色。

preload.js 脚本在 window对象中添加了一个新的 API叫做 深色模式。 此 API 暴露两个IPC 通道到渲染器进程，分别为 'dark-mode:toggle' 和 'dark-mode:system'。 它还分配了两个方法， toggle 和 system，它们将渲染器中的信息传递到 主进程。

preload.js

  1. const { contextBridge, ipcRenderer } = require('electron')
  3. contextBridge.exposeInMainWorld('darkMode', {
  4.   toggle: () => ipcRenderer.invoke('dark-mode:toggle'),
  5.   system: () => ipcRenderer.invoke('dark-mode:system')
  6. })

现在，渲染器进程可以安全地与主进程通信，并对nativeTheme 对象执行必要的变更。

renderer.js 文件负责控制 <button> 功能。

renderer.js

  1. document.getElementById('toggle-dark-mode').addEventListener('click', async () => {
  2.   const isDarkMode = await window.darkMode.toggle()
  3.   document.getElementById('theme-source').innerHTML = isDarkMode ? 'Dark' : 'Light'
  4. })
  6. document.getElementById('reset-to-system').addEventListener('click', async () => {
  7.   await window.darkMode.system()
  8.   document.getElementById('theme-source').innerHTML = 'System'
  9. })

使用 addEventListener， renderer.js 文件将'click' 事件监听器添加到每个按钮元素上。 每个事件监听处理器都会调用到相关的 window.darkmode API 方法。

最后， main.js 文件代表了主进程并包含实际的 nativeTheme API。

  1. const { app, BrowserWindow, ipcMain, nativeTheme } = require('electron')
  2. const path = require('node:path')
  4. const createWindow = () => {
  5.   const win = new BrowserWindow({
  6.     width: 800,
  7.     height: 600,
  8.     webPreferences: {
  9.       preload: path.join(__dirname, 'preload.js')
  10.     }
  11.   })
  13.   win.loadFile('index.html')
  15.   ipcMain.handle('dark-mode:toggle', () => {
  16.     if (nativeTheme.shouldUseDarkColors) {
  17.       nativeTheme.themeSource = 'light'
  18.     } else {
  19.       nativeTheme.themeSource = 'dark'
  20.     }
  21.     return nativeTheme.shouldUseDarkColors
  22.   })
  24.   ipcMain.handle('dark-mode:system', () => {
  25.     nativeTheme.themeSource = 'system'
  26.   })
  27. }
  29. app.whenReady().then(() => {
  30.   createWindow()
  32.   app.on('activate', () => {
  33.     if (BrowserWindow.getAllWindows().length === 0) {
  34.       createWindow()
  35.     }
  36.   })
  37. })
  39. app.on('window-all-closed', () => {
  40.   if (process.platform !== 'darwin') {
  41.     app.quit()
  42.   }
  43. })

ipcMain.handle 方法表明主进程如何响应来自 HTML 页面上 按钮的点击事件。

'dark-mode:toggle' IPC 通道处理器方法检查 shouldUseDarkColors boolean属性 设置对应的 themeSource, 然后返回当前的 shouldUseDarkColors 属性。 回顾此 IPC 通道的渲染器进程事件监听器，此处理器的返回值为 <strong id='theme-source'> 元素指定正确的文本。

'dark-mode:system' IPC 通道处理器方法将字符串 'system' 赋值到 themeSource 同时无返回值。 这也对应于相应的渲染器进程事件监听器，因为方法正在等待，且不需要返回值。

使用Electron Fiddle运行示例，然后点击“切换深色模式”按钮； 应用程序应该开始在亮色和黑色背景颜色之间交替。

Dark Mode