夜间模式

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

🌐 Ionic makes it easy to change the palettes of your app, including supporting dark color schemes. Dark mode is a display setting that changes all of an app's views to a dark palette. It has system-wide support on iOS and Android, making it highly desirable for developers to add to their apps.

启用深色调色板

🌐 Enabling Dark Palette

在应用中有三种提供的方式来启用暗色调：始终，根据系统设置，或使用 CSS 类。

🌐 There are three provided ways to enable the dark palette in an app: always, based on system settings, or by using a CSS class.

总是

🌐 Always

Ionic 框架提供的默认调色板是浅色调的，包括浅色背景和深色文字。然而，可以通过在相应的文件中导入以下样式表将默认调色板更改为深色调：

🌐 The default palette provided with Ionic Framework is a light palette, consisting of a light background and dark text. However, the default palette can be changed to the dark palette by importing the following stylesheet in the appropriate files:

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 选择器上设置 应用颜色 和 阶梯颜色。

🌐 This sets the application colors and stepped colors on the :root selector.

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

🌐 The following example will always display the dark palette, regardless of the system settings for dark mode.

重要的

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

系统

🌐 System

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

🌐 The system approach to enable dark mode involves checking the system settings for the user's preferred color scheme. This is the default when starting a new Ionic Framework app. Importing the following stylesheet in the appropriate file will automatically retrieve the user's preference from the system settings and apply the dark palette when dark mode is preferred:

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';

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

🌐 This sets the application colors and stepped colors when the CSS media query for prefers-color-scheme is dark. The prefers-color-scheme media query is supported by all modern browsers. If support for older browser is required, we recommend using the CSS class approach.

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

🌐 The following example uses the system settings to decide when to show dark mode.

info

不确定如何更改系统设置？以下是如何在 Windows 11 和 macOS 上启用夜间模式的方法。

重要的

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

CSS 类

🌐 CSS Class

虽然之前的方法通过仅导入文件就能很好地启用暗色调，但在某些情况下，你可能需要对其应用有更多的控制。比如，当你需要有条件地应用暗色调（例如通过切换）时，或者如果你想基于系统设置扩展功能，我们提供了一个暗色调类文件。将此文件中指定的类添加到应用中时，该文件会应用暗色调。将以下样式表导入到相应的文件中，将提供使用该类的暗色调所需的样式：

🌐 While the previous approaches are excellent for enabling the dark palette through file imports alone, there are scenarios where you may need more control over its application. In cases where you need to apply the dark palette conditionally, such as through a toggle, or if you want to extend the functionality based on system settings, we provide a dark palette class file. This file applies the dark palette when a specific class is added to an app. Importing the following stylesheet into the appropriate file will provide the necessary styles for using the dark palette with the class:

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 选择器上设置 应用颜色 和 分步颜色，开发者必须将其应用到应用中。

🌐 This sets the application colors and stepped colors on the .ion-palette-dark selector, which must be applied to the app by the developer.

以下示例结合了网站设置、系统设置以及用于决定何时显示夜间模式的切换。网站的调色板优先于系统设置。如果在演示加载时你的系统设置与网站的调色板不同，它将使用网站的调色板。

🌐 The following example combines site settings, system settings, and the toggle to decide when to show dark mode. The site's palette takes precedence over system settings. If your system settings differ from the site's palette when the demo loads, it will use the site's palette.

info

不确定如何更改系统设置？以下是如何在 Windows 11 和 macOS 上启用夜间模式的方法。

重要的

.ion-palette-dark 类 必须 添加到 html 元素中，以便与导入的深色调色板一起使用。

调整系统 UI 组件

🌐 Adjusting System UI Components

在开发深色调时，你可能会注意到某些系统 UI 组件未能正确适应夜间模式。要解决此问题，你需要指定 color-scheme。有关跨浏览器支持的详细信息，请参阅 颜色方案的浏览器兼容性 。

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

🌐 While you may be mainly using Ionic components instead of only native components, color-scheme can also affect aspects of your application such as the scrollbar. In order to use color-scheme you will need to add the following HTML to the head of your application:

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

这允许页面指示它适合使用哪种配色方案渲染。或者，你可以添加以下 CSS 来对每个元素单独进行设置：

🌐 This allows the page to indicate which color scheme it is comfortable being rendered with. Alternatively, you can add the following CSS to do this on a per-element basis:

color-scheme: light dark;

默认滚动条	带有 color-scheme 的滚动条

有关 color-scheme 的更多信息，请参阅 Web.dev 关于配色方案的指南。

🌐 For more information regarding color-scheme, please see the Web.dev guide on color schemes.

note

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

note

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

Ionic 深色调色板

🌐 Ionic Dark Palette

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

🌐 Ionic has a recommended dark palette that can be enabled in three different ways: always, based on system settings, or by using a CSS class. Each of these methods involves importing the dark palette file with the corresponding name.

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

🌐 The contents of each file are included below for reference. These variables are set by importing the relevant dark palette file and do not need to be copied into an app. For more information on the variables being changed, including additional variables for further customization, refer to the Themes section.

Always (dark.always.css)

始终黑暗的调色板表现如下：

🌐 The always dark palette behaves in the following ways:

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

caution

如果你想覆盖任何Ionic暗色调变量，注意特异性是很重要的。例如，因为每个模式都设置了--ion-item-background变量，所以它不能在:root选择器中被覆盖。需要一个特异性更高的选择器，例如:root.ios。

info

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

System (dark.system.css)

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

🌐 The system dark palette behaves in the following ways:

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

caution

如果你想覆盖任何Ionic暗色调变量，注意特异性是很重要的。例如，因为每个模式都设置了--ion-item-background变量，所以它不能在:root选择器中被覆盖。需要一个特异性更高的选择器，例如:root.ios。

info

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

Class (dark.class.css)

类深色调的表现方式如下：

🌐 The class dark palette behaves in the following ways:

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

caution

如果你想覆盖任何Ionic暗色调变量，注意特异性是很重要的。例如，因为每个模式都设置了--ion-item-background变量，所以不能在.ion-palette-dark选择器中覆盖它。需要使用特异性更高的选择器，例如.ion-palette-dark.ios。

info

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