实现深色主题

深色主题适用于 Android 10（API 级别 29）及更高版本。它具有以下优点：

根据设备的屏幕技术，可大幅降低功耗。
提高低视力用户和对强光敏感用户的可见性。
方便在低光照环境下使用设备。

深色主题应用于 Android 系统 UI 和设备上运行的应用。

在 Android 10 及更高版本中，启用深色主题有三种方法：

使用系统设置，导航到 **设置 > 显示 > 主题** 以启用深色主题。
启用后，使用快速设置磁贴从通知栏切换主题。
在 Pixel 设备上，启用省电模式可同时启用深色主题。其他设备可能不支持此行为。

有关使用 WebView 组件将深色主题应用于基于 Web 的内容的说明，请参阅在 WebView 中使 Web 内容变暗。

在您的应用中支持深色主题

要支持深色主题，请将应用的主题（通常位于 res/values/styles.xml 中）设置为继承自 DayNight 主题。

<style name="AppTheme" parent="Theme.AppCompat.DayNight">

您也可以使用 Material Components 深色主题

<style name="AppTheme" parent="Theme.MaterialComponents.DayNight">

这将应用的主要主题与系统控制的夜间模式标志绑定，并在启用夜间模式时为应用提供默认深色主题。

主题和样式

避免使用为浅色主题设计的硬编码颜色或图标。请改用主题属性或夜间限定资源。

对于深色主题，两个主题属性最重要：

?android:attr/textColorPrimary：通用文本颜色。在浅色主题中接近黑色，在深色主题中接近白色。包含禁用状态。
?attr/colorControlNormal：通用图标颜色。包含禁用状态。

我们建议使用 Material Design Components，因为它的颜色主题系统（例如主题属性 ?attr/colorSurface 和 ?attr/colorOnSurface）提供了易于访问的合适的颜色。您可以在主题中自定义这些属性。

在应用内更改主题

您可以允许用户在应用运行时更改应用的主题。以下是推荐的选项：

浅色
深色
系统默认值（推荐的默认选项）

这些选项直接映射到 AppCompat.DayNight 模式：

浅色：MODE_NIGHT_NO。
深色：MODE_NIGHT_YES。
系统默认值：MODE_NIGHT_FOLLOW_SYSTEM。

要切换主题，请执行以下操作：

在 API 级别 31 及更高版本上，使用 UiModeManager#setApplicationNightMode 让系统知道您的应用运行的主题。这允许系统在启动画面期间匹配主题。
在 API 级别 30 及以下版本上，使用 AppCompatDelegate.setDefaultNightMode() 切换主题。

强制深色模式

Android 10 提供了 *强制深色模式*，这是一个允许开发者快速实现深色主题的功能，无需显式设置 DayNight 主题。

强制深色模式会分析浅色主题应用的每个视图，并在将其绘制到屏幕之前自动应用深色主题。您可以混合使用强制深色模式和原生实现，以减少实现深色主题所需的时间。

应用必须通过在活动的主题中设置 android:forceDarkAllowed="true" 来选择加入强制深色模式。此属性设置为所有系统和 AndroidX 提供的浅色主题，例如 Theme.Material.Light。当您使用强制深色模式时，请彻底测试您的应用，并根据需要排除视图。

如果您的应用使用深色主题（例如 Theme.Material），则不会应用强制深色模式。同样，如果您的应用主题继承自 DayNight 主题，则由于自动主题切换，不会应用强制深色模式。

禁用视图上的强制深色模式

可以使用 android:forceDarkAllowed 布局属性或 setForceDarkAllowed() 控制特定视图上的强制深色模式。

Web 内容

有关在基于 Web 的内容中使用深色主题的信息，请参阅在 WebView 中使 Web 内容变暗。有关应用于 WebView 的深色主题示例，请参阅 GitHub 上的 WebView 演示。

最佳实践

以下部分提供了实施深色主题的最佳实践。

通知和小部件

对于您在设备上显示但不直接控制的 UI 表面，请确保您使用的任何视图都反映宿主应用的主题。两个示例是通知和启动器小部件。

通知

使用系统提供的通知模板，例如 MessagingStyle。这意味着系统负责应用正确的视图样式。

小部件和自定义通知视图

对于启动器小部件，或者如果您的应用使用自定义通知内容视图，请在浅色和深色主题上测试内容。

需要注意的一些常见陷阱包括：

假设背景颜色始终为浅色。
硬编码文本颜色。
使用默认文本颜色时设置硬编码背景颜色。
使用静态颜色的可绘制图标。

在所有这些情况下，请使用合适的主题属性代替硬编码颜色。

启动画面

如果您的应用有自定义启动画面，您可能需要对其进行修改，以便它反映所选主题。

删除任何硬编码颜色，例如以编程方式设置为白色的背景颜色。请改用 ?android:attr/colorBackground 主题属性。

配置更改

当应用的主题通过系统设置或 AppCompat 更改时，它会触发 uiMode 配置更改。这意味着活动会自动重新创建。

在某些情况下，您可能希望应用处理配置更改。例如，您可能希望延迟配置更改，因为正在播放视频。

应用可以通过声明每个Activity都能处理uiMode配置更改来实现深色主题。

<activity
    android:name=".MyActivity"
    android:configChanges="uiMode" />

当Activity声明它处理配置更改时，主题更改时会调用其onConfigurationChanged()方法。

要检查当前主题是什么，应用可以运行如下代码：

Kotlin

val currentNightMode = configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
when (currentNightMode) {
    Configuration.UI_MODE_NIGHT_NO -> {} // Night mode is not active, we're using the light theme.
    Configuration.UI_MODE_NIGHT_YES -> {} // Night mode is active, we're using dark theme.
}

Java

int currentNightMode = configuration.uiMode & Configuration.UI_MODE_NIGHT_MASK;
switch (currentNightMode) {
    case Configuration.UI_MODE_NIGHT_NO:
        // Night mode is not active, we're using the light theme
        break;
    case Configuration.UI_MODE_NIGHT_YES:
        // Night mode is active, we're using dark theme
        break;
}