Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

Условия приложения	Веб-контент, использующий `prefers-color-scheme`	Веб-контент, который не использует `prefers-color-scheme`
Приложение использует светлую тему оформления, при этом параметр `isLightTheme` может быть установлен в `true` или нет.	WebView отображает контент со светлой темой, которая Автор контента определил это.	WebView отображает контент с использованием стилей по умолчанию, определенных автором контента.
В приложении используется функция Force Dark для алгоритмического применения темной темы .	WebView отображает контент в темной теме, которая Автор контента определил это.	Если автор контента разрешит это, WebView отобразит контент в темной теме, которая генерируется с помощью алгоритма.
Приложение использует темную тему с `isLightTheme` , установленным в значение `false` , и не позволяет алгоритмически затемнять WebView.	WebView отображает контент в темной теме, которая Автор контента определил это.	WebView отображает контент с использованием стилей по умолчанию, определенных автором контента.
Приложение использует темную тему с параметром `isLightTheme` , установленным в значение `false` , и позволяет алгоритмически затемнять WebView .	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 .

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

Включите алгоритмическое затемнение веб-контента с помощью функции Force Dark.

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

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

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

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

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

Для приложений, которые не используют принудительное затемнение на уровне приложения и ориентированы на Android 13 (уровень API 33) или выше, используйте метод Jetpack Webkit 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 :

Котлин

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

Java

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

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

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

Вы также можете использовать API ForceDarkStrategy из библиотеки Jetpack для управления тем, как применяется затемнение к конкретному 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(...)
}

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 веб-страницы. Вы можете использовать WebView с режимом 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.

Затемнение веб-контента в WebView Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

оформление контента автором

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

Включите алгоритмическое затемнение веб-контента с помощью функции Force Dark.

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

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

Котлин

Java

Котлин

Java

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

Котлин

Java

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