在 WebView 中调暗 Web 内容

在 Android 10 及更高版本中，应用可以支持深色主题，并根据系统主题自动在浅色和深色应用主题之间切换。为了与当前应用主题保持一致，WebView 中的 Web 内容还可以使用浅色、深色或默认样式。

WebView 的行为可与 prefers-color-scheme 和 color-scheme 网络标准互操作。如果您要编写要让应用在 WebView 中显示的网页内容，请尽可能为您的网站定义深色主题并实现 prefers-color-scheme，以便 WebView 可以将网页内容的主题与应用的主题进行匹配。

下表介绍了 WebView 如何根据 Web 内容的样式和应用的条件在应用中呈现 Web 内容：

应用条件	使用 prefers-color-scheme 的 Web 内容	不使用 prefers-color-scheme 的网页内容
应用使用浅色主题，且 isLightTheme 设置为 true 或未设置。	WebView 会使用内容作者定义的浅色主题呈现内容。	WebView 会使用内容作者定义的默认样式呈现内容。
应用使用 Force Dark 以算法方式将深色主题应用到应用。	WebView 会使用内容作者定义的深色主题呈现内容。	如果内容作者允许，WebView 会使用使用算法生成的深色主题呈现内容。
应用使用深色主题，并将 isLightTheme 设为 false，并且应用不允许对 WebView 使用算法调暗。	WebView 使用内容作者定义的深色主题来呈现内容。	WebView 会使用内容作者定义的默认样式呈现内容。
应用使用深色主题，并将 isLightTheme 设为 false，并且应用允许 对 WebView 使用算法调暗。	WebView 会使用内容作者定义的深色主题呈现内容。	如果内容作者允许，WebView 会使用使用算法生成的深色主题呈现内容。

内容作者样式

应用的 isLightTheme 属性指示应用的主题是浅色还是深色。WebView 始终会根据 isLightTheme 设置 prefers-color-scheme。如果 isLightTheme 为 true 或未指定，则 prefers-color-scheme 为 light；否则为 dark。

这意味着，如果 Web 内容使用 prefers-color-scheme 且内容作者允许，系统会始终自动将内容作者定义的浅色或深色主题应用于 Web 内容，以匹配应用的主题。

算法调暗

为了涵盖 Web 内容不使用 prefers-color-scheme 的情况，您的应用可以允许 WebView 在必要时通过算法将深色主题应用于其呈现的 Web 内容。

如果您的应用使用应用级 Force Dark 以算法方式为应用应用深色主题，请参阅下一部分，了解如何允许 Force Dark 对网络内容进行算法调暗。

如果您的应用未使用 Force Dark，则应用如何指定何时允许在 WebView 中使用算法深色模式取决于应用的目标 API 级别。如需了解详情，请参阅以 Android 13 或更高版本为目标平台的应用和以 Android 12 或更低版本为目标平台的应用部分。

允许使用 Force Dark 对网页内容进行算法调暗

如果您的应用使用的是应用级 Force Dark，当满足以下条件时，WebView 会对 Web 内容应用算法调暗功能：

• WebView 及其父元素支持强制深色。
• 当前 activity 主题被标记为浅色，isLightTheme 设置为 true。
• 网站内容作者未明确停用深色模式。
• 对于以 Android 13（API 级别 33）或更高版本为目标平台的应用，Web 内容不使用 prefers-color-scheme，
• 对于以 Android 12（API 级别 32）或更低版本为目标平台的应用：应用已将 WebView 的 forceDarkMode 设置设为 FORCE_DARK_AUTO，并将强制深色策略设为 DARK_STRATEGY_USER_AGENT_DARKENING_ONLY。

WebView 及其所有父级均可使用 View.setForceDarkAllowed() 允许强制深色。默认值取自 Android 主题的 setForceDarkAllowed() 属性，该属性也必须设置为 true。

强制深色模式主要用于在未提供自己的深色主题的应用中实现向后兼容性。如果您的应用使用 Force Dark，我们建议您添加对深色主题的支持。

允许算法调暗（以 Android 13 或更高版本为目标平台的应用）

对于未使用应用级 Force Dark 且以 Android 13（API 级别 33）或更高版本为目标平台的应用，请使用 AndroidX setAlgorithmicDarkeningAllowed() 方法并传入 true，以指定 WebView 应允许通过算法加深。此方法向后兼容之前的 Android 版本。

如果满足以下条件，WebView 就会应用算法加深功能：

• 网页内容不使用 prefers-color-scheme。
• 网络内容作者没有明确停用调暗功能。

允许算法加深（以 Android 12 或更低版本为目标平台的应用）

对于未使用应用级强制深色模式且以 Android 12（API 级别 32）或更低版本为目标平台的应用，请使用 FORCE_DARK_ON 来允许算法调暗。

如果您的应用提供了在浅色和深色主题之间切换的自己的方法（例如界面中的可切换元素或基于时间的自动选择），请将 FORCE_DARK_ON 与 FORCE_DARK_OFF 搭配使用。

如需检查是否支持该功能，请在配置 WebView 对象的任何位置（例如 Activity.onCreate 中）添加以下代码行：

Kotlin

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) {
    WebSettingsCompat.setForceDark(...)
}

Java

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) {
    WebSettingsCompat.setForceDark(...);
}

如果您的应用依赖于检测系统偏好设置的更改，则应明确监听主题更改，并使用 FORCE_DARK_ON 和 FORCE_DARK_OFF 状态将其应用于 WebView。

以下代码段展示了如何更改主题格式：

Kotlin

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) {
    when (resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK) {
        Configuration.UI_MODE_NIGHT_YES -> {
            WebSettingsCompat.setForceDark(myWebView.settings, FORCE_DARK_ON)
        }
        Configuration.UI_MODE_NIGHT_NO, Configuration.UI_MODE_NIGHT_UNDEFINED -> {
            WebSettingsCompat.setForceDark(myWebView.settings, FORCE_DARK_OFF)
        }
        else -> {
            //
        }
    }
}

Java

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) {
    switch (getResources().getConfiguration().uiMode & Configuration.UI_MODE_NIGHT_MASK) {
        case Configuration.UI_MODE_NIGHT_YES:
            WebSettingsCompat.setForceDark(myWebView.getSettings(), FORCE_DARK_ON);
            break;
        case Configuration.UI_MODE_NIGHT_NO:
        case Configuration.UI_MODE_NIGHT_UNDEFINED:
            WebSettingsCompat.setForceDark(myWebView.getSettings(), FORCE_DARK_OFF);
            break;
    }
}

自定义深色主题处理

您还可以使用 AndroidX 中的 ForceDarkStrategy API 来控制将调暗功能应用于指定 WebView 的方式。此 API 仅在强制深色设置为 FORCE_DARK_ON 或 FORCE_DARK_AUTO 时才适用。

借助此 API，您的应用可以使用 Web 主题深色或用户代理深色：

• 网页主题加深：Web 开发者可以应用 @media (prefers-color-scheme: dark) 来控制网页在深色模式下的显示效果。WebView 会根据这些设置呈现内容。如需详细了解网页主题加深功能，请参阅规范。
• 用户代理加深：WebView 会自动反转网页的颜色。如果您使用了用户代理深色处理，则 @media (prefers-color-scheme: dark) 查询的值会评估为 false。

如需在两种策略之间进行选择，请使用以下 API：

Kotlin

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK_STRATEGY)) {
    WebSettingsCompat.setForceDarkStrategy(...)
}

Java

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK_STRATEGY)) {
    WebSettingsCompat.setForceDarkStrategy(...);
}

支持的策略选项包括：

• DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING：这是默认选项。虽然大多数浏览器都将 <meta name="color-scheme" content="dark light"> 标记视为可选标记，但 Android WebView 的默认模式要求元标记遵循网页的 prefers-color-scheme 媒体查询。您可以在 DARK_STRATEGY_WEB_THEME_DARKENING_ONLY 模式下使用 WebView，在这种情况下，即使省略了标记，WebView 也会始终应用媒体查询。

  不过，我们建议 Web 开发者向其网站添加 <meta name="color-scheme" content="dark light"> 标记，以确保内容在采用默认配置的 WebView 中正确呈现。

• DARK_STRATEGY_USER_AGENT_DARKENING_ONLY：称为“user-agent 加深”，WebView 会忽略任何网页加深并应用自动加深。

如果您的应用显示您使用 prefers-color-scheme 媒体查询自定义的第一方 Web 内容，我们建议您DARK_STRATEGY_WEB_THEME_DARKENING_ONLY，以确保 WebView 使用自定义主题。

如需查看应用深色主题的示例，请参阅 GitHub 上的 WebView 演示