Esta página foi traduzida pela API Cloud Translation.

Escurecer conteúdo da Web no WebView

No Android 10 e versões mais recentes, um app pode oferecer suporte a uma tema escuro e mudar automaticamente entre os temas claro e escuro do app de acordo com o tema do sistema. Para corresponder ao tema atual do app, conteúdo da Web no WebView também podem usar o estilo claro, escuro ou padrão.

O comportamento do WebView interopera com o prefers-color-scheme e color-scheme os padrões da Web. Sempre que possível, se você for o autor do conteúdo da Web que deseja que seu app mostre na WebView, é necessário definir um tema escuro para o site e implementar prefers-color-scheme para que a WebView possa corresponder ao ao tema do seu app.

A tabela a seguir descreve como a WebView renderiza conteúdo da Web no seu app. dependendo do estilo do conteúdo da Web e das condições do seu app:

Condições do app	Conteúdo da Web que usa `prefers-color-scheme`	Conteúdo da Web que não usa `prefers-color-scheme`
O app está usando um tema claro com `isLightTheme` definido como `true` ou não definido.	A WebView renderiza o conteúdo com o tema claro que definido pelo autor do conteúdo.	A WebView renderiza o conteúdo com o estilo padrão definido pelo autor do conteúdo.
O app está usando Forçar modo escuro para aplicar um tema escuro com algoritmos para o app.	A WebView renderiza o conteúdo com o tema escuro que definido pelo autor do conteúdo.	Se permitido pelo autor do conteúdo, a WebView renderiza o conteúdo com uma tema escuro gerado usando um algoritmo.
O app está usando um tema escuro com `isLightTheme` definido como `false`, e o app não permite algoritmos escurecimento para WebView.	A WebView renderiza o conteúdo com o tema escuro que definido pelo autor do conteúdo.	A WebView renderiza o conteúdo com o estilo padrão definido pelo autor do conteúdo.
O app está usando um tema escuro com `isLightTheme` definido como `false`, e o app permite escurecimento algorítmico para WebView.	A WebView renderiza o conteúdo com o tema escuro que definido pelo autor do conteúdo.	Se permitido pelo autor do conteúdo, a WebView renderiza o conteúdo com uma tema escuro gerado usando um algoritmo.

Estilo do autor do conteúdo

Os Atributo isLightTheme indica se o tema do app é claro ou escuro. O WebView sempre define prefers-color-scheme de acordo com isLightTheme. Se isLightTheme for true ou não especificado, prefers-color-scheme será light; caso contrário, dark.

Isso significa que, se o conteúdo da Web usar prefers-color-scheme e o autor permite, o tema claro ou escuro definido pelo autor do conteúdo é sempre aplicada automaticamente ao conteúdo da Web para corresponder ao tema do app.

Escurecimento algorítmico

Para cobrir casos em que o conteúdo da Web não usa prefers-color-scheme, seu app pode permitir que a WebView aplique algo escuro por meio de algoritmos, quando necessário ao conteúdo da Web que ele renderiza.

Caso seu app use a API Forçar modo escuro para definir algorítmico aplicar um tema escuro no app, consulte a seção abaixo, que descreve como Permitir o escurecimento algorítmico de conteúdo da Web com o recurso Forçar modo escuro.

Se o app não usa o Forçar modo escuro, como ele especifica quando permitir o escurecimento algorítmico no WebView depende do comportamento nível desejado da API. Consulte as seções a seguir para apps destinados ao Android 13 ou mais recente e apps destinados ao Android 12 ou versões anteriores para saber mais detalhes.

Permitir o escurecimento de algoritmos para conteúdo da Web com o recurso "Forçar modo escuro"

Caso seu app use a API Forçar modo escuro: a WebView aplica escurecimento algorítmico para conteúdo da Web se as seguintes condições forem atendidas:

A WebView e os elementos pais dela permitem "Forçar modo escuro".
O tema da atividade atual está marcado como claro com isLightTheme definido como true.
O autor do conteúdo da Web não desativa o escurecimento explicitamente.
Em apps destinados ao Android 13 (nível 33 da API) ou versões mais recentes, o conteúdo da Web não usa prefers-color-scheme;
Para apps destinados ao Android 12 (nível 32 da API) ou versões anteriores: o app definiu Configuração forceDarkMode do WebView para FORCE_DARK_AUTO e definiu a estratégia Force Dark para DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

O WebView e todos os pais dele podem permitir o escurecimento forçado usando View.setForceDarkAllowed() O valor padrão é retirado do atributo setForceDarkAllowed() da Tema do Android, que também precisa ser definido como true.

O recurso Forçar modo escuro é fornecido principalmente para compatibilidade com versões anteriores em apps que não forneçam um tema escuro próprio. Caso seu app use o Forçar modo escuro, recomendamos adição de compatibilidade com um tema escuro.

Permitir o escurecimento de algoritmos (apps destinados ao Android 13 ou mais recente)

Para apps que não usam o recurso Forçar modo escuro no nível do app e são direcionados ao Android 13 (nível da API) 33) ou mais recente, use a versão do AndroidX setAlgorithmicDarkeningAllowed() e transmitir true para especificar que uma WebView deve permitir o uso de algoritmos escurecer. Esse método tem compatibilidade com versões anteriores do Android mais recentes.

Em seguida, o WebView aplicará o escurecimento algorítmico se as seguintes condições forem atendidas:

O conteúdo da Web não usa prefers-color-scheme.
O autor do conteúdo da Web não desativa o escurecimento explicitamente.

Permitir o escurecimento de algoritmos (apps destinados ao Android 12 ou versões anteriores)

Para apps que não usam o recurso Forçar modo escuro no nível do app e são direcionados ao Android 12 (nível da API) 32) ou inferior, use FORCE_DARK_ON para permitir o escurecimento algorítmico.

Use FORCE_DARK_ON junto com FORCE_DARK_OFF se o app oferece o próprio método para alternar entre os temas claro e escuro, como um elemento alternável na interface ou uma seleção automática baseada em tempo.

Para verificar se o recurso é compatível, adicione as seguintes linhas de código sempre que você configurar o objeto da WebView, como em Activity.onCreate:

Kotlin

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

Java

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

Se o app depende da detecção de mudanças nas preferências do sistema, ele precisa: detectar explicitamente as mudanças de tema e aplicá-las ao WebView com Estados FORCE_DARK_ON e FORCE_DARK_OFF.

O snippet de código abaixo mostra como mudar o formato do tema:

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

Personalizar o processamento do tema escuro

Você também pode usar o API ForceDarkStrategy no AndroidX para controlar como o escurecimento é aplicado a uma determinada WebView. Essa API é aplicável somente se o modo escuro for definido como FORCE_DARK_ON ou FORCE_DARK_AUTO.

Com a API, seu app pode usar o escurecimento do tema da Web ou o user agent escurecimento:

Escurecimento do tema da Web: os desenvolvedores Web podem aplicar @media (prefers-color-scheme: dark) para controlar a aparência da página da Web em modo escuro. O WebView renderiza conteúdo de acordo com essas configurações. Para saber mais sobre escurecimento do tema da Web, consulte especificação.
Escurecimento do user agent: a WebView inverte automaticamente as cores da Web. página. Se você usar o escurecimento do user agent, A consulta @media (prefers-color-scheme: dark) é avaliada como false.

Para escolher entre as duas estratégias, use a seguinte API:

Kotlin

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

Java

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

As opções de estratégia aceitas são:

DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING: Essa é a opção padrão. Embora a maioria dos navegadores trate a Tag <meta name="color-scheme" content="dark light"> como opcional, Android O modo padrão do WebView exige que a metatag siga o padrão prefers-color-scheme consultas de mídia. É possível usar WebViews com DARK_STRATEGY_WEB_THEME_DARKENING_ONLY Nesse caso, a WebView sempre aplica consultas de mídia, mesmo que a tag seja omitido.

No entanto, recomendamos que os desenvolvedores da Web adicionem <meta name="color-scheme" content="dark light"> aos seus sites para garantir que o conteúdo seja renderizado corretamente em WebViews com a configuração padrão.
DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: Chamado de "escurecimento do user agent" a WebView ignora qualquer escurecimento de página da Web e aplica o escurecimento automático.

Caso seu app mostre conteúdo da Web próprio que você personalizou com o prefers-color-scheme consulta de mídia, recomendamos DARK_STRATEGY_WEB_THEME_DARKENING_ONLY para garantir que o WebView use o tema personalizado.

Para conferir um exemplo de aplicação do tema escuro, consulte a Demonstração do WebView no GitHub