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 di sistema. Per abbinarsi al tema dell'app corrente, i contenuti web in WebView possono utilizzare anche stili chiari, scuri o predefiniti.

Il comportamento di WebView è interoperabile con gli standard web di prefers-color-scheme e color-scheme. Se possibile, se sei l'autore dei contenuti web che vuoi che la tua app mostri 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 in che modo WebView esegue il rendering dei contenuti web nella tua app, a seconda dello stile dei contenuti web e delle condizioni dell'app:

Stile dell'autore dei contenuti

L'attributo isLightTheme di un'app indica se il tema è 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 lo consente, il tema chiaro o scuro definito dall'autore viene sempre applicato automaticamente ai contenuti web in modo che corrispondano al tema dell'app.

Oscuramento degli algoritmi

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 in modo algoritmico un tema scuro ai contenuti web che vengono visualizzati.

Se la tua app utilizza Force Dark a livello di app per applicare un tema scuro tramite algoritmo, consulta la seguente sezione che descrive come consentire il darkening algoritmico per i contenuti web con Force Dark.

Se la tua app non utilizza la modalità Forza scuro, il modo in cui specifica quando consentire l'oscuramento algoritmico in WebView dipende dal livello API target dell'app. Per informazioni dettagliate sulle app destinate ad Android 13 o versioni successive e sulle app destinate ad Android 12 o versioni precedenti, consulta le sezioni seguenti.

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

Se la tua app utilizza la modalità Forza modalità scura a livello di app, WebView applica l'oscuramento algoritmico ai contenuti web se sono soddisfatte le seguenti condizioni:

• WebView e i relativi elementi principali consentono la modalità Force Dark.
• Il tema dell'attività corrente è contrassegnato come chiaro con isLightTheme impostato su true.
• L'autore dei contenuti web non disattiva esplicitamente il 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 configurato l'impostazione forceDarkMode di WebView su FORCE_DARK_AUTO e ha impostato la strategia Forza Buio su DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

WebView e tutti i suoi elementi principali possono consentire l'applicazione forzata del tema scuro utilizzando View.setForceDarkAllowed(). Il valore predefinito viene recuperato dall'attributo setForceDarkAllowed() del tema Android, che deve essere anch'esso impostato su true.

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

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

Per le app che non utilizzano Force Dark a livello di app e hanno come target Android 13 (livello API 33) o versioni successive, utilizza il metodo AndroidX setAlgorithmicDarkeningAllowed() e passa il valore true per specificare che un componente WebView deve consentire il oscuramento algoritmo. Questo metodo ha la compatibilità 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 il oscuramento.

Consenti l'oscuramento algoritmico (app destinate ad Android 12 o versioni precedenti)

Per le app che non utilizzano la modalità Scura forzata 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 il 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 in base all'ora.

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

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

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

Se la tua app si basa sul rilevamento delle modifiche alle preferenze di sistema, deve monitorare esplicitamente le modifiche del 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:

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

Personalizzare la gestione del tema scuro

Puoi anche utilizzare l'API ForceDarkStrategy in AndroidX per controllare il modo in cui l'oscuramento viene applicato a un determinato WebView. Questa API è applicabile solo se il oscuramento forzato è impostato su FORCE_DARK_ON o FORCE_DARK_AUTO.

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

• Appiattimento del tema web: gli sviluppatori web potrebbero applicare @media (prefers-color-scheme: dark) per controllare l'aspetto della pagina web in modalità scura. WebView esegue il rendering dei contenuti in base a queste impostazioni. Per saperne di più sull'oscuramento del tema web, consulta la specifica.
• Oscuramento dell'user-agent: 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:

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

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 query multimediali della pagina web. Puoi utilizzare le WebView con la modalità DARK_STRATEGY_WEB_THEME_DARKENING_ONLY, in questo caso WebView applica sempre le query sui media anche se il tag è omesso.

  Tuttavia, consigliamo agli sviluppatori web di aggiungere il tag <meta name="color-scheme" content="dark light"> ai propri siti web per garantire il rendering corretto dei contenuti nelle visualizzazioni web con la configurazione predefinita.

• DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: chiamato "oscuramento dell'user-agent", WebView ignora l'oscuramento della pagina web e applica l'oscuramento automatico.

Se la tua app mostra contenuti web proprietari personalizzati con la query mediaprefers-color-scheme, ti consigliamoDARK_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.