Scurisci i contenuti web in WebView

In Android 10 e versioni successive, un'app può supportare un tema scuro e passare automaticamente dal tema chiaro a quello scuro in base al tema del sistema. Per abbinare il tema dell'app corrente, i contenuti web in WebView possono anche utilizzare uno stile chiaro, scuro o predefinito.

Il comportamento di WebView interagisce con gli standard web prefers-color-scheme e color-scheme. Se possibile, se crei i contenuti web che vuoi che la tua app visualizzi in WebView, devi definire un tema scuro per il tuo sito web e implementare prefers-color-scheme in modo che WebView possa abbinare il tema dei contenuti web al tema della tua app.

La tabella seguente descrive come WebView esegue il rendering dei contenuti web nella tua app, a seconda dello stile dei contenuti web e delle condizioni della tua app:

Condizioni dell'app Contenuti web che utilizzano prefers-color-scheme Contenuti web che non utilizzano prefers-color-scheme
L'app utilizza un tema chiaro con isLightTheme impostato su true o non impostato. WebView esegue il rendering dei contenuti con il tema chiaro definito dall'autore dei contenuti. WebView esegue il rendering dei contenuti con lo stile predefinito definito dall'autore dei contenuti.
L'app utilizza tema scuro forzato per applicare algoritmicamente un tema scuro all'app. WebView esegue il rendering dei contenuti con il tema scuro che l'autore dei contenuti ha definito. Se consentito dall'autore dei contenuti, WebView esegue il rendering dei contenuti con un tema scuro generato utilizzando un algoritmo.
L'app utilizza un tema scuro con isLightTheme impostato su false e l'app non consente lo scurimento algoritmico per WebView. WebView esegue il rendering dei contenuti con il tema scuro che l'autore dei contenuti ha definito. WebView esegue il rendering dei contenuti con lo stile predefinito definito dall'autore dei contenuti.
L'app utilizza un tema scuro con isLightTheme impostato su false e l'app consente l'oscuramento algoritmico per WebView. WebView esegue il rendering dei contenuti con il tema scuro che l'autore dei contenuti ha definito. Se consentito dall'autore dei contenuti, WebView esegue il rendering dei contenuti con un tema scuro generato utilizzando un algoritmo.

Stile dell'autore dei contenuti

L'attributo isLightTheme di un'app indica se il tema dell'app è chiaro o scuro. WebView imposta sempre prefers-color-scheme in base a isLightTheme. Se isLightTheme è true o non è specificato, prefers-color-scheme è light; altrimenti, è dark.

Ciò significa che se i contenuti web utilizzano prefers-color-scheme e l'autore dei contenuti lo consente, il tema chiaro o scuro definito dall'autore dei contenuti viene sempre applicato automaticamente ai contenuti web in modo che corrisponda al tema dell'app.

Oscuramento algoritmico

Per coprire i casi in cui i contenuti web non utilizzano prefers-color-scheme, la tua app può consentire a WebView, se necessario, di applicare algoritmicamente un tema scuro ai contenuti web che esegue il rendering.

Se la tua app utilizza la funzionalità tema scuro forzato a livello di app per applicare in modo algoritmico un tema scuro all'app, consulta la sezione seguente che descrive come consentire l'oscuramento algoritmico per i contenuti web con tema scuro forzato.

Se la tua app non utilizza il tema scuro forzato, il modo in cui specifica quando consentire l'oscuramento algoritmico in WebView dipende dal livello API target della tua app. Per maggiori dettagli, consulta le sezioni seguenti per le app che hanno come target Android 13 o versioni successive e per le app che hanno come target Android 12 o versioni precedenti.

Consenti l'oscuramento algoritmico per i contenuti web con tema scuro forzato

Se la tua app utilizza la funzionalità tema scuro forzato a livello di app, WebView applica l'oscuramento algoritmico ai contenuti web se vengono soddisfatte le seguenti condizioni:

  • La WebView e i relativi elementi principali consentono la modalità Buio forzato.
  • Il tema dell'attività corrente è contrassegnato come chiaro con isLightTheme impostato su true.
  • L'autore dei contenuti web non disattiva esplicitamente l'oscuramento.
  • Per le app che hanno come target Android 13 (livello API 33) o versioni successive, i contenuti web non utilizzano prefers-color-scheme.
  • Per le app che hanno come target Android 12 (livello API 32) o versioni precedenti: l'app ha impostato l'impostazione forceDarkMode di WebView su FORCE_DARK_AUTO e ha impostato la strategia del tema scuro forzato su DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

WebView e tutti i relativi genitori possono consentire la modalità Buio forzata utilizzando View.setForceDarkAllowed(). Il valore predefinito viene preso dall'attributo setForceDarkAllowed() del tema Android, che deve essere impostato anche su true.

La modalità Buio forzato è fornita principalmente per la compatibilità con le versioni precedenti nelle app che non forniscono un proprio tema scuro. Se la tua app utilizza il tema scuro forzato, ti consigliamo di aggiungere il supporto per un tema scuro.

Consenti oscuramento algoritmico (app destinate ad Android 13 o versioni successive)

Per le app che non utilizzano il tema scuro forzato a livello di app e hanno come target Android 13 (livello API 33) o versioni successive, utilizza il metodo Jetpack Webkit setAlgorithmicDarkeningAllowed() e trasmetti true per specificare che una WebView deve consentire l'oscuramento algoritmico. Questo metodo è compatibile con le versioni precedenti di Android.

WebView applica quindi l'oscuramento algoritmico se sono soddisfatte le seguenti condizioni:

  • I contenuti web non utilizzano prefers-color-scheme.
  • L'autore dei contenuti web non disattiva esplicitamente l'oscuramento.

Consenti oscuramento algoritmico (app che hanno come target Android 12 o versioni precedenti)

Per le app che non utilizzano il tema scuro forzato a livello di app e hanno come target Android 12 (livello API 32) o versioni precedenti, utilizza FORCE_DARK_ON per consentire l'oscuramento algoritmico.

Utilizza FORCE_DARK_ON insieme a FORCE_DARK_OFF se la tua app fornisce un proprio metodo per passare dal tema chiaro a quello scuro e viceversa, ad esempio un elemento attivabile/disattivabile nell'interfaccia utente o una selezione automatica basata sul tempo.

Per verificare se la funzionalità è supportata, aggiungi le seguenti righe di codice ovunque configuri l'oggetto WebView, ad esempio in Activity.onCreate:

Kotlin

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

Java

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

Se la tua app si basa sul rilevamento delle modifiche alle preferenze di sistema, deve ascoltare esplicitamente le modifiche al tema e applicarle a WebView con gli stati FORCE_DARK_ON e FORCE_DARK_OFF.

Il seguente snippet di codice mostra come modificare il formato del 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;
    }
}

Personalizzare la gestione del tema scuro

Puoi anche utilizzare l'API ForceDarkStrategy nella libreria Jetpack per controllare la modalità di applicazione dell'oscuramento a una determinata WebView. Questa API è applicabile solo se l'oscuramento forzato è impostato su FORCE_DARK_ON o FORCE_DARK_AUTO.

Utilizzando l'API, la tua app può utilizzare l'oscuramento del tema web o l'oscuramento dello user agent:

  • Oscuramento del tema web: gli sviluppatori web potrebbero applicare @media (prefers-color-scheme: dark) per controllare l'aspetto delle pagine web in modalità Buio. WebView esegue il rendering dei contenuti in base a queste impostazioni. Per saperne di più sull'oscuramento del tema web, consulta la specifica.
  • Oscuramento dello user agent: la WebView inverte automaticamente i colori della pagina web. Se utilizzi l'oscuramento dello user agent, la query @media (prefers-color-scheme: dark) viene valutata come false.

Per scegliere tra le due strategie, utilizza la seguente API:

Kotlin

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

Java

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

Le opzioni di strategia supportate sono:

  • DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING: questa è l'opzione predefinita. Anche se la maggior parte dei browser considera il tag <meta name="color-scheme" content="dark light"> come facoltativo, la modalità predefinita di Android WebView richiede che il meta tag rispetti le prefers-color-scheme media query della pagina web. Puoi utilizzare le WebView con la modalità DARK_STRATEGY_WEB_THEME_DARKENING_ONLY, nel qual caso WebView applica sempre le media query anche se il tag viene omesso.

    Tuttavia, consigliamo agli sviluppatori web di aggiungere il tag <meta name="color-scheme" content="dark light"> ai propri siti web per assicurarsi che i contenuti vengano visualizzati correttamente nelle WebView con la configurazione predefinita.

  • DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: Chiamato "oscuramento dello user agent", WebView ignora qualsiasi oscuramento della pagina web e applica l'oscuramento automatico.

Se la tua app mostra contenuti web proprietari che hai personalizzato con la query multimediale prefers-color-scheme, ti consigliamo DARK_STRATEGY_WEB_THEME_DARKENING_ONLY di assicurarti che WebView utilizzi il tema personalizzato.

Per un esempio di applicazione del tema scuro, consulta la demo di WebView su GitHub.