Затемнение веб-контента в WebView

В Android 10 и более поздних версиях приложение может поддерживать темную тему и автоматически переключаться между светлой и темной темами приложения в соответствии с системной темой. Чтобы соответствовать текущей теме приложения, веб-контент в WebView также может использовать светлый, темный стиль или стиль по умолчанию.

Поведение WebView взаимодействует с веб-стандартами prefers-color-scheme и color-scheme . Если это возможно, если вы создаете веб-контент, который хотите, чтобы ваше приложение отображалось в WebView, вам следует определить темную тему для вашего веб-сайта и реализовать prefers-color-scheme , чтобы WebView мог сопоставлять тему веб-контента с темой вашего приложения.

В следующей таблице описано, как WebView отображает веб-содержимое в вашем приложении, в зависимости от стиля веб-содержимого и условий вашего приложения.

Контент-авторский стиль

Атрибут isLightTheme приложения указывает, является ли тема приложения светлой или темной. WebView всегда устанавливает prefers-color-scheme в соответствии с isLightTheme . Если isLightTheme имеет true или не указано, то prefers-color-scheme light ; иначе dark .

Это означает, что если веб-контент использует prefers-color-scheme и автор контента разрешает это, светлая или темная тема, определенная автором контента, всегда автоматически применяется к веб-контенту в соответствии с темой приложения.

Алгоритмическое затемнение

Чтобы охватить случаи, когда веб-контент не использует prefers-color-scheme , ваше приложение может разрешить WebView при необходимости алгоритмически применять темную тему к отображаемому веб-контенту.

Если ваше приложение использует Force Dark на уровне приложения для алгоритмического применения темной темы к вашему приложению, см. следующий раздел, в котором описывается, как разрешить алгоритмическое затемнение веб-контента с помощью Force Dark .

Если ваше приложение не использует Force Dark, то, как ваше приложение определяет, когда разрешать алгоритмическое затемнение в WebView, зависит от целевого уровня API вашего приложения. Подробную информацию о приложениях для Android 13 или более поздней версии и приложениях для Android 12 или более ранней версии см. в следующих разделах.

Разрешите алгоритмическое затемнение веб-контента с помощью Force Dark

Если ваше приложение использует Force Dark на уровне приложения, WebView применяет алгоритмическое затемнение к веб-содержимому, если выполняются следующие условия:

• WebView и его родительские элементы поддерживают Force Dark.
• Текущая тема активности помечается как легкая, если для isLightTheme установлено значение true .
• Автор веб-контента не отключает затемнение явным образом.
• Для приложений, предназначенных для Android 13 (уровень API 33) или более поздних версий, веб-контент не использует prefers-color-scheme .
• Для приложений, ориентированных на Android 12 (уровень API 32) или ниже: приложение установило для параметра forceDarkMode WebView значение FORCE_DARK_AUTO , а для стратегии Force Dark — значение DARK_STRATEGY_USER_AGENT_DARKENING_ONLY .

WebView и все его родители могут разрешить принудительное темное использование View.setForceDarkAllowed() . Значение по умолчанию берется из атрибута setForceDarkAllowed() темы Android, которому также должно быть присвоено значение true .

Режим Force Dark предназначен в первую очередь для обеспечения обратной совместимости в приложениях, которые не имеют собственной темной темы . Если ваше приложение использует Force Dark, мы рекомендуем добавить поддержку темной темы .

Разрешить алгоритмическое затемнение (приложения для Android 13 или более поздней версии)

Для приложений, которые не используют Force Dark на уровне приложения и ориентированы на Android 13 (уровень API 33) или выше, используйте метод AndroidX setAlgorithmicDarkeningAllowed() и передайте true чтобы указать, что WebView должен разрешать алгоритмическое затемнение. Этот метод имеет обратную совместимость с предыдущими версиями Android.

Затем WebView применяет алгоритмическое затемнение, если выполняются следующие условия:

• Веб-контент не использует prefers-color-scheme .
• Автор веб-контента не отключает затемнение явным образом.

Разрешить алгоритмическое затемнение (приложения для Android 12 или более ранней версии)

Для приложений, которые не используют Force Dark на уровне приложения и ориентированы на Android 12 (уровень API 32) или ниже, используйте FORCE_DARK_ON , чтобы разрешить алгоритмическое затемнение.

Используйте FORCE_DARK_ON вместе с FORCE_DARK_OFF , если ваше приложение предоставляет собственный метод переключения между светлой и темной темами, например переключаемый элемент в пользовательском интерфейсе или автоматический выбор на основе времени.

Чтобы проверить, поддерживается ли эта функция, добавьте следующие строки кода везде, где вы настраиваете объект WebView, например, в Activity.onCreate :

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

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

Если ваше приложение полагается на обнаружение изменений в системных настройках, ваше приложение должно явно прослушивать изменения темы и применять их к WebView с состояниями FORCE_DARK_ON и FORCE_DARK_OFF .

В следующем фрагменте кода показано, как изменить формат темы:

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 -> {
            //
        }
    }
}

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

Настройте обработку темной темы

Вы также можете использовать API ForceDarkStrategy в AndroidX, чтобы контролировать, как затемнение применяется к данному WebView. Этот API применим только в том случае, если для параметра Force Dark установлено значение FORCE_DARK_ON или FORCE_DARK_AUTO .

Используя API, ваше приложение может использовать либо затемнение веб-темы, либо затемнение пользовательского агента:

• Затемнение веб-темы . Веб-разработчики могут применять @media (prefers-color-scheme: dark) для управления внешним видом веб-страницы в темном режиме. WebView отображает контент в соответствии с этими настройками. Подробнее о затемнении веб-темы см. в спецификации .
• Затемнение пользовательского агента : WebView автоматически инвертирует цвета веб-страницы. Если вы используете затемнение пользовательского агента, запрос @media (prefers-color-scheme: dark) оценивается как false .

Чтобы выбрать между двумя стратегиями, используйте следующий API:

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

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 веб-страницы. Вы можете использовать WebViews с режимом DARK_STRATEGY_WEB_THEME_DARKENING_ONLY , и в этом случае WebView всегда применяет медиа-запросы, даже если тег опущен.

  Однако мы рекомендуем веб-разработчикам добавлять тег <meta name="color-scheme" content="dark light"> на свои веб-сайты, чтобы обеспечить правильное отображение контента в WebViews с конфигурацией по умолчанию.

• DARK_STRATEGY_USER_AGENT_DARKENING_ONLY : так называемое «затемнение пользовательского агента», WebView игнорирует любое затемнение веб-страницы и применяет автоматическое затемнение.

Если ваше приложение отображает собственный веб-контент, который вы настроили с помощью медиа-запроса prefers-color-scheme , мы рекомендуем DARK_STRATEGY_WEB_THEME_DARKENING_ONLY чтобы гарантировать, что WebView использует пользовательскую тему.

Пример применения темной темы см. в демонстрации WebView на GitHub.