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 os temas claro e escuro de acordo com o tema do sistema. Para corresponder ao tema atual do app, o conteúdo da Web no WebView também pode usar estilos claro, escuro ou padrão.

O comportamento do WebView interopera com os prefers-color-scheme e color-scheme padrões da Web. Sempre que possível, se você criar o conteúdo da Web que quer que seu app mostre no WebView, defina um tema escuro para seu site e implemente prefers-color-scheme para que o WebView possa corresponder ao tema do conteúdo da Web com o tema do app.

A tabela a seguir descreve como o WebView renderiza o conteúdo da Web no seu app, dependendo do estilo do conteúdo da Web e das condições do 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. O WebView renderiza o conteúdo com o tema claro que o autor do conteúdo definiu. O WebView renderiza o conteúdo com o estilo padrão definido pelo autor do conteúdo.
O app está usando Forçar tema escuro para aplicar um tema escuro ao app de forma algorítmica. O WebView renderiza o conteúdo com o tema escuro que o autor do conteúdo definiu. Se permitido pelo autor do conteúdo, o WebView renderiza o conteúdo com um tema escuro gerado usando um algoritmo.
O app está usando um tema escuro com isLightTheme definido como false e o app não permite escurecimento algorítmico para o WebView. O WebView renderiza o conteúdo com o tema escuro que o autor do conteúdo definiu. O 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 o escurecimento algorítmico para o WebView. O WebView renderiza o conteúdo com o tema escuro que o autor do conteúdo definiu. Se permitido pelo autor do conteúdo, o WebView renderiza o conteúdo com um tema escuro gerado usando um algoritmo.

Estilo do autor do conteúdo

O atributo isLightTheme de um app 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 for 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 do conteúdo permitir, o tema claro ou escuro definido pelo autor do conteúdo será sempre aplicado 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 o WebView, quando necessário, aplique um tema escuro de forma algorítmica ao conteúdo da Web que ele renderiza.

Se o app estiver usando o recurso Forçar tema escuro no nível do app para aplicar um tema escuro de forma algorítmica, consulte a seção a seguir, que descreve como permitir o escurecimento algorítmico para conteúdo da Web com o recurso Forçar tema 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 desejado da API do app . Consulte as seções a seguir para apps direcionados ao Android 13 ou versões mais recentes e apps direcionados ao Android 12 ou versões anteriores para mais detalhes.

Permitir o escurecimento algorítmico para conteúdo da Web com o recurso Forçar tema escuro

Se o app estiver usando o recurso Forçar tema escuro no nível do app, o WebView vai aplicar o escurecimento algorítmico ao conteúdo da Web se as seguintes condições forem atendidas:

  • O WebView e os elementos pai permitem o recurso Forçar tema 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 explicitamente o escurecimento.
  • Para apps direcionados 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 direcionados ao Android 12 (nível 32 da API) ou versões anteriores: o app definiu a configuração do WebView forceDarkModecomo FORCE_DARK_AUTO e definiu a estratégia do recurso Forçar modo escuro como DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

O WebView e todos os pais dele podem permitir o recurso Forçar modo escuro 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 Forçar tema escuro é fornecido principalmente para oferecer compatibilidade com versões anteriores em apps que não oferecem o próprio tema escuro. Se o app usar o recurso Forçar tema escuro, recomendamos adicionar suporte a um tema escuro.

Permitir o escurecimento algorítmico (apps direcionados ao Android 13 ou versões mais recentes)

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

O 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 direcionados ao Android 12 ou versões anteriores)

Para apps que não estão usando 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 fornecer o próprio método para alternar entre temas claros e escuros, como um elemento alternável na interface ou uma seleção automática baseada no tempo.

Para verificar se o recurso é compatível, adicione as seguintes linhas de código onde você configura o objeto 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 os estados FORCE_DARK_ON e FORCE_DARK_OFF.

O snippet de código a seguir 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 a API ForceDarkStrategy na biblioteca Jetpack para controlar como o escurecimento é aplicado a um determinado WebView. Essa API é aplicável apenas se o recurso Forçar modo escuro estiver definido como FORCE_DARK_ON ou FORCE_DARK_AUTO.

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

  • Escurecimento 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 mais informações sobre o escurecimento do tema da Web, consulte a especificação.
  • Escurecimento do user agent: o 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:

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 com suporte são:

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

    No entanto, recomendamos que os desenvolvedores da 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", o WebView ignora qualquer escurecimento da página da Web e aplica o escurecimento automático.

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

Para ver um exemplo de tema escuro aplicado, consulte a demonstração do WebView no GitHub (link em inglês).