版本：v6

深色模式

Ionic 使得更改应用的主题变得容易，包括支持深色配色方案。随着原生应用对深色模式的支持日益增长，开发者现在希望将其添加到自己的应用中以支持用户偏好。

使用媒体查询

启用深色模式的第一种方法是使用 CSS 媒体查询检测用户偏好的配色方案。此媒体查询将挂钩用户设备的系统设置，并在启用深色模式时应用主题。

@media (prefers-color-scheme: dark) {
  :root {
    /* 深色模式变量在此处 */
  }
}

目前，prefers-color-scheme 媒体查询的浏览器支持有限，因此用户在某些浏览器中无法通过此媒体查询受益于深色模式。但是，仍然可以通过使用 CSS 类回退来应用深色模式。

CSS 类回退

作为不支持媒体查询的设备的回退方法，可以通过样式化 CSS 选择器并将类应用于文档 body 来应用深色模式。

@media (prefers-color-scheme: dark) {
  :root {
    /* 深色模式变量在此处 */
  }
}

/* 旧版浏览器或手动模式的回退 */
body.dark {
  /* 深色模式变量在此处 */
}

通过针对 body.dark 选择器的变量，现在只需要将类添加到应用中的 <body> 即可。这可以通过多种方式实现，具体取决于您的应用所使用的框架。

请注意，在此示例中，变量应同时存在于两个位置。我们可以使用 JavaScript 来避免在两个地方设置变量。

与 JavaScript 结合使用

为了保持 CSS 变量只编写一次并避免在多个地方更新，可以通过使用 JavaScript 检查 prefers-color-scheme 媒体查询的值，并在偏好为 dark 时添加 dark 类，从而将回退和类结合起来。CSS 如下所示：

body.dark {
  /* 深色模式变量在此处 */
}

请注意，上面的变量现在只在 body.dark 选择器中，而 prefers-color-scheme 媒体查询已被移除。

自动启用深色模式

在 JavaScript 中，可以通过使用 matchMedia() 检查文档是否匹配媒体查询，将 dark 类添加到 <body>。这将使深色模式仍然基于用户偏好工作。

// 使用 matchMedia 检查用户偏好
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)');

toggleDarkTheme(prefersDark.matches);

// 监听 prefers-color-scheme 媒体查询的变化
prefersDark.addEventListener('change', (mediaQuery) => toggleDarkTheme(mediaQuery.matches));

// 根据媒体查询是否匹配来添加或移除 "dark" 类
function toggleDarkTheme(shouldAdd) {
  document.body.classList.toggle('dark', shouldAdd);
}

备注

提示：请确保在支持的浏览器中查看下面的 Codepen，然后尝试在您的设备上更改系统偏好，在浅色和深色模式之间切换。这里是如何在 Windows 10 上启用深色模式以及如何在 Mac 上启用深色模式。

手动切换深色模式

除了在应用加载时和媒体查询更改时调用 toggleDarkTheme()，应用还可以调用 toggleDarkTheme() 函数，例如当用户更改切换开关时，以在浅色和深色主题之间切换：

// 查询用于在主题之间切换的 toggle 元素
const toggle = document.querySelector('#themeToggle');

// 监听 toggle 的选中/取消选中以在 <body> 上切换 dark 类
toggle.addEventListener('ionChange', (ev) => {
  document.body.classList.toggle('dark', ev.detail.checked);
});

const prefersDark = window.matchMedia('(prefers-color-scheme: dark)');

// 监听 prefers-color-scheme 媒体查询的变化
prefersDark.addEventListener('change', (e) => checkToggle(e.matches));

// 应用加载时调用
function loadApp() {
  checkToggle(prefersDark.matches);
}

// 由媒体查询调用以选中/取消选中 toggle
function checkToggle(shouldCheck) {
  toggle.checked = shouldCheck;
}

调整系统 UI 组件

在开发深色主题时，您可能会注意到某些系统 UI 组件没有正确调整为深色模式。要解决这个问题，您需要指定 color-scheme。请参阅 color-scheme 的浏览器兼容性以了解跨浏览器支持的详细信息。

虽然您可能主要使用 Ionic 组件而不是仅使用原生组件，但 color-scheme 也会影响应用程序的某些方面，例如滚动条。要使用 color-scheme，您需要在应用的 head 中添加以下 HTML：

<meta name="color-scheme" content="light dark" />

这允许页面指示它适合以哪种配色方案进行渲染。或者，您可以添加以下 CSS 以在每个元素的基础上执行此操作：

color-scheme: light dark;

默认滚动条	使用 `color-scheme` 的滚动条

有关 color-scheme 的更多信息，请参阅 https://web.dev/color-scheme/。

备注

color-scheme 不适用于键盘。有关深色模式如何与键盘配合使用的详细信息，请参阅键盘文档。

备注

对于希望在 Safari on iOS 15 的状态栏下方或 Safari on macOS 的工具栏中自定义主题颜色的开发者，请参阅 theme-color Meta。

Ionic 深色主题

Ionic 有一个推荐的变量主题，用于根据运行应用的设备获取深色模式。它可以分为以下几个部分：

更改所有模式的默认 Ionic 颜色，以在 body.dark 选择器中补充深色背景。
为 ios 设备设置深色主题的变量。
为 md 设备设置深色主题的变量。

以下代码可以复制粘贴到应用中，以获得 Ionic 的深色主题。我们使用 JavaScript 将 dark 类添加到文档 body，如与 JavaScript 结合使用部分所述。在将 dark 类添加到文档 body 之前，深色模式不会启用。

备注

有关正在更改的变量的更多信息，包括可以添加以进一步自定义的其他变量，请参阅主题。

/*
 * 深色颜色
 * -------------------------------------------
 */

body.dark {
  --ion-color-primary: #428cff;
  --ion-color-primary-rgb: 66, 140, 255;
  --ion-color-primary-contrast: #ffffff;
  --ion-color-primary-contrast-rgb: 255, 255, 255;
  --ion-color-primary-shade: #3a7be0;
  --ion-color-primary-tint: #5598ff;

  --ion-color-secondary: #50c8ff;
  --ion-color-secondary-rgb: 80, 200, 255;
  --ion-color-secondary-contrast: #ffffff;
  --ion-color-secondary-contrast-rgb: 255, 255, 255;
  --ion-color-secondary-shade: #46b0e0;
  --ion-color-secondary-tint: #62ceff;

  --ion-color-tertiary: #6a64ff;
  --ion-color-tertiary-rgb: 106, 100, 255;
  --ion-color-tertiary-contrast: #ffffff;
  --ion-color-tertiary-contrast-rgb: 255, 255, 255;
  --ion-color-tertiary-shade: #5d58e0;
  --ion-color-tertiary-tint: #7974ff;

  --ion-color-success: #2fdf75;
  --ion-color-success-rgb: 47, 223, 117;
  --ion-color-success-contrast: #000000;
  --ion-color-success-contrast-rgb: 0, 0, 0;
  --ion-color-success-shade: #29c467;
  --ion-color-success-tint: #44e283;

  --ion-color-warning: #ffd534;
  --ion-color-warning-rgb: 255, 213, 52;
  --ion-color-warning-contrast: #000000;
  --ion-color-warning-contrast-rgb: 0, 0, 0;
  --ion-color-warning-shade: #e0bb2e;
  --ion-color-warning-tint: #ffd948;

  --ion-color-danger: #ff4961;
  --ion-color-danger-rgb: 255, 73, 97;
  --ion-color-danger-contrast: #ffffff;
  --ion-color-danger-contrast-rgb: 255, 255, 255;
  --ion-color-danger-shade: #e04055;
  --ion-color-danger-tint: #ff5b71;

  --ion-color-dark: #f4f5f8;
  --ion-color-dark-rgb: 244, 245, 248;
  --ion-color-dark-contrast: #000000;
  --ion-color-dark-contrast-rgb: 0, 0, 0;
  --ion-color-dark-shade: #d7d8da;
  --ion-color-dark-tint: #f5f6f9;

  --ion-color-medium: #989aa2;
  --ion-color-medium-rgb: 152, 154, 162;
  --ion-color-medium-contrast: #000000;
  --ion-color-medium-contrast-rgb: 0, 0, 0;
  --ion-color-medium-shade: #86888f;
  --ion-color-medium-tint: #a2a4ab;

  --ion-color-light: #222428;
  --ion-color-light-rgb: 34, 36, 40;
  --ion-color-light-contrast: #ffffff;
  --ion-color-light-contrast-rgb: 255, 255, 255;
  --ion-color-light-shade: #1e2023;
  --ion-color-light-tint: #383a3e;
}

/*
 * iOS 深色主题
 * -------------------------------------------
 */

.ios body.dark {
  --ion-background-color: #000000;
  --ion-background-color-rgb: 0, 0, 0;

  --ion-text-color: #ffffff;
  --ion-text-color-rgb: 255, 255, 255;

  --ion-color-step-50: #0d0d0d;
  --ion-color-step-100: #1a1a1a;
  --ion-color-step-150: #262626;
  --ion-color-step-200: #333333;
  --ion-color-step-250: #404040;
  --ion-color-step-300: #4d4d4d;
  --ion-color-step-350: #595959;
  --ion-color-step-400: #666666;
  --ion-color-step-450: #737373;
  --ion-color-step-500: #808080;
  --ion-color-step-550: #8c8c8c;
  --ion-color-step-600: #999999;
  --ion-color-step-650: #a6a6a6;
  --ion-color-step-700: #b3b3b3;
  --ion-color-step-750: #bfbfbf;
  --ion-color-step-800: #cccccc;
  --ion-color-step-850: #d9d9d9;
  --ion-color-step-900: #e6e6e6;
  --ion-color-step-950: #f2f2f2;

  --ion-item-background: #000000;

  --ion-card-background: #1c1c1d;
}

.ios body.dark ion-modal {
  --ion-background-color: var(--ion-color-step-100);
  --ion-toolbar-background: var(--ion-color-step-150);
  --ion-toolbar-border-color: var(--ion-color-step-250);
  --ion-item-background: var(--ion-color-step-150);
}

/*
 * Material Design 深色主题
 * -------------------------------------------
 */

.md body.dark {
  --ion-background-color: #121212;
  --ion-background-color-rgb: 18, 18, 18;

  --ion-text-color: #ffffff;
  --ion-text-color-rgb: 255, 255, 255;

  --ion-border-color: #222222;

  --ion-color-step-50: #1e1e1e;
  --ion-color-step-100: #2a2a2a;
  --ion-color-step-150: #363636;
  --ion-color-step-200: #414141;
  --ion-color-step-250: #4d4d4d;
  --ion-color-step-300: #595959;
  --ion-color-step-350: #656565;
  --ion-color-step-400: #717171;
  --ion-color-step-450: #7d7d7d;
  --ion-color-step-500: #898989;
  --ion-color-step-550: #949494;
  --ion-color-step-600: #a0a0a0;
  --ion-color-step-650: #acacac;
  --ion-color-step-700: #b8b8b8;
  --ion-color-step-750: #c4c4c4;
  --ion-color-step-800: #d0d0d0;
  --ion-color-step-850: #dbdbdb;
  --ion-color-step-900: #e7e7e7;
  --ion-color-step-950: #f3f3f3;

  --ion-item-background: #1e1e1e;

  --ion-toolbar-background: #1f1f1f;

  --ion-tab-bar-background: #1f1f1f;

  --ion-card-background: #1e1e1e;
}

使用媒体查询​

CSS 类回退​

与 JavaScript 结合使用​

自动启用深色模式​

手动切换深色模式​

调整系统 UI 组件​

Ionic 深色主题​

目录