Escurecer conteúdo da Web no WebView

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

O comportamento da WebView interage com os padrões da Web prefers-color-scheme e color-scheme. Quando possível, se você criar o conteúdo da Web que quer que o app mostre na WebView, defina um tema escuro para seu site e implemente prefers-color-scheme para que a WebView possa corresponder ao tema do conteúdo da Web ao tema do 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 app:

Estilo do autor do conteúdo

O atributo isLightTheme de um app indica se o tema dele é claro ou escuro. A 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, será dark.

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

Escurecimento algorítmico

Para casos em que o conteúdo da Web não usa prefers-color-scheme, seu app pode permitir que a WebView, quando necessário, aplique um tema escuro algorítmico ao conteúdo da Web que ela renderiza.

Se o app estiver usando o nível do app Forçar modo escuro para aplicar um tema escuro algoritmicamente, consulte a seção a seguir que descreve como permitir o escurecimento algorítmico do conteúdo da Web com o recurso Forçar modo escuro.

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

Permitir o escurecimento algorítmico para conteúdo da Web com o recurso de forçar modo escuro

Se o app estiver usando o recurso Force Dark (link em inglês) no nível do app, a WebView vai aplicar o escurecimento algorítmico ao 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 de atividade atual está marcado como claro com isLightTheme definido como true.
• O autor do conteúdo da Web não desativa explicitamente o escurecimento.
• Em apps direcionados ao Android 13 (nível 33 da API) ou mais recente, o conteúdo da Web não usa prefers-color-scheme.
• Para apps direcionados ao Android 12 (nível 32 da API) ou versões anteriores: o app definiu a configuração forceDarkMode do WebView como FORCE_DARK_AUTO e definiu a estratégia de Forçar modo escuro como DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

A WebView e todos os elementos pai podem permitir o modo escuro forçado usando View.setForceDarkAllowed(). O valor padrão é extraído do atributo setForceDarkAllowed() do tema do Android, que também precisa ser definido como true.

O modo "Forçar modo escuro" é fornecido principalmente para compatibilidade com versões anteriores em apps que não oferecem o próprio tema escuro. Se o app usa o Forçar modo escuro, recomendamos adicionar suporte a um tema escuro.

Permitir o escurecimento algorítmico (apps destinados ao Android 13 ou mais recente)

Para apps que não usam o recurso "Forçar o modo escuro" no nível do app e são direcionados ao Android 13 (nível 33 da API) ou mais recente, use o método setAlgorithmicDarkeningAllowed() do AndroidX e transmita true para especificar que uma WebView precisa permitir o escurecimento algorítmico. Esse método tem compatibilidade com versões anteriores do Android.

A WebView aplica 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 explicitamente o escurecimento.

Permitir o escurecimento algorítmico (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 32 da API) ou versões anteriores, use FORCE_DARK_ON para permitir o escurecimento algorítmico.

Use FORCE_DARK_ON com FORCE_DARK_OFF se o app tiver um método próprio para alternar entre temas claros e escuros, como um elemento comutável na interface ou uma seleção automática baseada no tempo.

Para verificar se o recurso tem suporte, adicione as seguintes linhas de código sempre que configurar o objeto WebView, como em Activity.onCreate:

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

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 à WebView com os estados FORCE_DARK_ON e FORCE_DARK_OFF.

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

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

Personalizar o processamento do tema escuro

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

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

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

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

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

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

As opções de estratégia compatíveis são:

• DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING: esta é a opção padrão. Embora a maioria dos navegadores trate a tag <meta name="color-scheme" content="dark light"> como opcional, o modo padrão do Android WebView exige que a metatag atenda às consultas de mídia prefers-color-scheme da página da Web. Você pode usar as WebViews com o modo DARK_STRATEGY_WEB_THEME_DARKENING_ONLY. Nesse caso, a WebView sempre aplica consultas de mídia, mesmo que a tag seja omitida.

  No entanto, recomendamos que os desenvolvedores Web adicionem a tag <meta name="color-scheme" content="dark light"> aos 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 da página da Web e aplica o escurecimento automático.

Se o app mostra conteúdo da Web personalizado com a consulta de mídia prefers-color-scheme, recomendamos DARK_STRATEGY_WEB_THEME_DARKENING_ONLY para garantir que a WebView use o tema personalizado.

Para conferir um exemplo de tema escuro aplicado, consulte a demonstração da WebView no GitHub.