Scurisci i contenuti web in WebView

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

Il comportamento di WebView interagisce con gli standard web di prefers-color-scheme e color-scheme. Quando possibile, se crei i 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 dell'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:

Stili autore di 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 corrispondano al tema dell'app.

Oscuramento algoritmico

Per trattare 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 di cui esegue il rendering.

Se la tua app utilizza il pulsante Forza scuro a livello di app per applicare algoritmicamente un tema scuro alla tua app, consulta la sezione seguente che descrive come consentire il oscuramento algoritmico per i contenuti web con questo tema.

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

Consenti il oscuramento algoritmico per i contenuti web con il tema scuro forzato

Se la tua app usa il scuro forzato a livello di app, WebView applica il oscuramento algoritmico ai contenuti web se sono soddisfatte le seguenti condizioni:

• WebView e gli elementi principali consentono il tema scuro forzato.
• Il tema dell'attività corrente è contrassegnato come chiaro con isLightTheme impostato su true.
• L'autore di 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 impostato l'impostazione forceDarkMode di WebView su FORCE_DARK_AUTO e la strategia Forza scuro su DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

WebView e tutti i suoi elementi principali possono consentire il buio forzato 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 garantire la compatibilità con le versioni precedenti delle app che non offrono un tema scuro proprio. Se la tua app utilizza il tema scuro forzato, ti consigliamo di aggiungere il supporto per il tema scuro.

Consenti il oscuramento algoritmico (app che hanno come target Android 13 o versioni successive)

Per le app che non utilizzano Force Dark a livello di app e di destinazione Android 13 (livello API 33) o versioni successive, utilizza il metodo AndroidX setAlgorithmicDarkeningAllowed() e passa in true per specificare che un componente WebView deve consentire l'oscuramento algoritmico. Questo metodo è compatibile con le versioni precedenti di Android.

WebView applica quindi il oscuramento algoritmico se vengono soddisfatte le seguenti condizioni:

• I contenuti web non usano prefers-color-scheme.
• L'autore di contenuti web non disattiva esplicitamente il oscuramento.

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

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

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

Per verificare se la funzionalità è supportata, aggiungi le seguenti righe di codice ogni volta che 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 ascoltare 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;
    }
}

Personalizza la gestione del tema scuro

Puoi anche utilizzare l'API ForceDarkStrategy in AndroidX per controllare la modalità di applicazione dello scurimento a una determinata WebView. Questa API è applicabile solo se il tema scuro forzato è impostato su FORCE_DARK_ON o FORCE_DARK_AUTO.

Mediante l'API, la tua app può utilizzare lo scurimento del tema web o dello user agent:

• Scuro del tema web: gli sviluppatori web potrebbero applicare @media (prefers-color-scheme: dark) per controllare l'aspetto delle pagine web in modalità Buio. WebView mostra i contenuti in base a queste impostazioni. Per ulteriori informazioni sullo scurimento dei temi web, consulta la specifica.
• Scurimento dello user agent: il componente WebView inverte automaticamente i colori della pagina web. Se utilizzi il oscuramento dello user agent, la query @media (prefers-color-scheme: dark) restituisce 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. Sebbene la maggior parte dei browser consideri il tag <meta name="color-scheme" content="dark light"> facoltativo, la modalità predefinita di Android WebView richiede che il meta tag rispetti le query supporti prefers-color-scheme della pagina web. Puoi utilizzare WebView con la modalità DARK_STRATEGY_WEB_THEME_DARKENING_ONLY. In questo caso, WebView applica sempre le query supporti anche se il tag viene omesso.

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

• DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: denominato "scurimento user agent", il componente WebView ignora qualsiasi scurimento delle pagine web e applica lo 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 tema scuro applicato, vedi la demo di WebView su GitHub