深色模式

Ionic 使得更改应用的配色方案变得简单，包括支持深色配色方案。深色模式是一种显示设置，可将应用的所有视图切换为深色调色板。它在 iOS 和 Android 上具有系统级的支持，因此开发者非常希望将其添加到他们的应用中。

启用深色调色板

有三种提供的方法可以在应用中启用深色调色板：始终启用、基于系统设置启用，或通过使用 CSS 类启用。

始终启用

Ionic Framework 提供的默认调色板是浅色调色板，由浅色背景和深色文本组成。但是，可以通过在适当的文件中导入以下样式表，将默认调色板更改为深色调色板：

Angular

@import '@ionic/angular/css/palettes/dark.always.css';

Javascript

import '@ionic/core/css/palettes/dark.always.css';

React

import '@ionic/react/css/palettes/dark.always.css';

Vue

import '@ionic/vue/css/palettes/dark.always.css';

这将在 :root 选择器上设置应用颜色和阶梯颜色。

以下示例将始终显示深色调色板，无论系统深色模式设置如何。

重要提醒

避免使用 .ios 或 .md 选择器来覆盖 Ionic 深色调色板，因为这些类会添加到每个组件中，并且优先级高于全局定义的变量。相反，我们可以针对 :root 元素上的特定模式类。

系统设置

启用深色模式的系统方法涉及检查系统设置中用户偏好的配色方案。这是开始新的 Ionic Framework 应用时的默认设置。在适当的文件中导入以下样式表将自动从系统设置中获取用户的偏好，并在偏好深色模式时应用深色调色板：

Angular

@import '@ionic/angular/css/palettes/dark.system.css';

Javascript

import '@ionic/core/css/palettes/dark.system.css';

React

import '@ionic/react/css/palettes/dark.system.css';

Vue

import '@ionic/vue/css/palettes/dark.system.css';

这将在 CSS 媒体查询 prefers-color-scheme 为 dark 时设置应用颜色和阶梯颜色。prefers-color-scheme 媒体查询得到所有现代浏览器的支持。如果需要支持旧版浏览器，我们建议使用 CSS 类方法。

以下示例使用系统设置来决定何时显示深色模式。

信息

不确定如何更改系统设置？以下是启用深色模式的方法：Windows 11 和 macOS。

重要提醒

避免使用 .ios 或 .md 选择器来覆盖 Ionic 深色调色板，因为这些类会添加到每个组件中，并且优先级高于全局定义的变量。相反，我们可以针对 :root 元素上的特定模式类。

CSS 类

虽然上述方法非常适合仅通过文件导入来启用深色调色板，但在某些情况下，您可能需要对其应用进行更多控制。如果您需要有条件地应用深色调色板（例如通过切换开关），或者希望基于系统设置扩展功能，我们提供了深色调色板类文件。该文件在将特定类添加到应用时应用深色调色板。在适当的文件中导入以下样式表将提供使用深色调色板类所需的样式：

Angular

@import '@ionic/angular/css/palettes/dark.class.css';

Javascript

import '@ionic/core/css/palettes/dark.class.css';

React

import '@ionic/react/css/palettes/dark.class.css';

Vue

import '@ionic/vue/css/palettes/dark.class.css';

这将在 .ion-palette-dark 选择器上设置应用颜色和阶梯颜色，该类必须由开发者应用到应用中。

以下示例结合了站点设置、系统设置和切换开关来决定何时显示深色模式。站点的调色板优先级高于系统设置。如果演示加载时您的系统设置与站点的调色板不同，它将使用站点的调色板。

信息

不确定如何更改系统设置？以下是启用深色模式的方法：Windows 11 和 macOS。

重要提醒

.ion-palette-dark 类必须添加到 html 元素中，才能与导入的深色调色板一起工作。

调整系统 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 的更多信息，请参阅 Web.dev 关于配色方案的指南。

备注

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

备注

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

Ionic 深色调色板

Ionic 提供了一个推荐的深色调色板，可以通过三种不同的方式启用：始终启用、基于系统设置启用，或通过使用 CSS 类启用。每种方法都涉及导入具有相应名称的深色调色板文件。

每个文件的内容如下所示，供参考。这些变量是通过导入相关的深色调色板文件设置的，无需复制到应用中。有关正在更改的变量的更多信息，包括用于进一步自定义的其他变量，请参阅主题部分。

始终启用 (dark.always.css)

始终启用的深色调色板的行为方式如下：

1. 在 :root 选择器上为所有模式设置 Ionic 颜色以补充深色调色板。:root 选择器与 html 选择器相同，只是其特异性更高。
2. 使用 :root.ios 选择器为 ios 设备设置深色调色板变量。
3. 使用 :root.md 选择器为 md 设备设置深色调色板变量。

警告

如果您想覆盖任何 Ionic 深色调色板变量，请务必注意特异性。例如，因为 --ion-item-background 变量是为每种模式设置的，所以不能在 :root 选择器中覆盖它。需要使用更高特异性的选择器，例如 :root.ios。

信息

Ionic 深色调色板的内容可以在 GitHub 上查看。用于应用始终启用深色调色板的 CSS 可以在仓库中找到。

系统设置 (dark.system.css)

系统设置的深色调色板的行为方式如下：

1. 在 :root 选择器上为所有模式设置 Ionic 颜色以补充深色调色板。:root 选择器与 html 选择器相同，只是其特异性更高。
2. 使用 :root.ios 选择器为 ios 设备设置深色调色板变量。
3. 使用 :root.md 选择器为 md 设备设置深色调色板变量。
4. 仅当 CSS 媒体查询 prefers-color-scheme 为 dark 时才应用这些变量。

警告

如果您想覆盖任何 Ionic 深色调色板变量，请务必注意特异性。例如，因为 --ion-item-background 变量是为每种模式设置的，所以不能在 :root 选择器中覆盖它。需要使用更高特异性的选择器，例如 :root.ios。

信息

Ionic 深色调色板的内容可以在 GitHub 上查看。用于应用系统设置深色调色板的 CSS 可以在仓库中找到。

CSS 类 (dark.class.css)

CSS 类的深色调色板的行为方式如下：

1. 在 .ion-palette-dark 选择器上为所有模式设置 Ionic 颜色以补充深色调色板。.ion-palette-dark 类必须添加到应用中的 html 元素。
2. 使用 .ion-palette-dark.ios 选择器为 ios 设备设置深色调色板变量。
3. 使用 .ion-palette-dark.md 选择器为 md 设备设置深色调色板变量。

警告

如果您想覆盖任何 Ionic 深色调色板变量，请务必注意特异性。例如，因为 --ion-item-background 变量是为每种模式设置的，所以不能在 .ion-palette-dark 选择器中覆盖它。需要使用更高特异性的选择器，例如 .ion-palette-dark.ios。

信息

Ionic 深色调色板的内容可以在 GitHub 上查看。用于应用CSS 类深色调色板的 CSS 可以在仓库中找到。