Questa pagina è stata tradotta dall'API Cloud Translation.

Scurisci i contenuti web in WebView

In Android 10 e versioni successive, un'app può supportare una Tema scuro e la funzionalità cambia automaticamente tra temi dell'app chiari e scuri in base al tema di sistema. Per rispettare i tema dell'app corrente, contenuti web in WebView puoi anche usare lo stile chiaro, scuro o predefinito.

Il comportamento di WebView interagisce con prefers-color-scheme e color-scheme standard web. Quando possibile, se crei i contenuti web che desideri visualizzare l'app in WebView, devi definire un tema scuro per il tuo sito web e implementare prefers-color-scheme in modo che WebView possa corrispondere ai contenuti web tema al tema della tua app.

La seguente tabella 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:

Condizioni per le app	Contenuti web che utilizzano `prefers-color-scheme`	Contenuti web che non utilizzano `prefers-color-scheme`
L'app usa un tema chiaro con `isLightTheme` impostato su `true` o non impostato.	WebView esegue il rendering dei contenuti con il tema chiaro che definiti dall'autore dei contenuti.	WebView esegue il rendering dei contenuti con lo stile predefinito definito dalla autore di contenuti.
L'app sta usando Scuro forzato a applicare tramite algoritmo un tema scuro all'app.	WebView esegue il rendering dei contenuti con il tema scuro che definiti dall'autore dei contenuti.	Se consentito dall'autore dei contenuti, WebView esegue il rendering dei contenuti con un tema scuro generato tramite un algoritmo.
L'app utilizza un tema scuro con `isLightTheme` impostata su `false` e l'app non consente la definizione di algoritmi per WebView.	WebView esegue il rendering dei contenuti con il tema scuro che definiti dall'autore dei contenuti.	WebView esegue il rendering dei contenuti con lo stile predefinito definito dalla autore di contenuti.
L'app utilizza un tema scuro con `isLightTheme` impostata su `false` e l'app consente oscuramento algoritmico per WebView.	WebView esegue il rendering dei contenuti con il tema scuro che definiti dall'autore dei contenuti.	Se consentito dall'autore dei contenuti, WebView esegue il rendering dei contenuti con un tema scuro generato tramite un algoritmo.

Stili dell'autore dei contenuti

Il Attributo isLightTheme indica se il tema dell'app è chiaro o scuro. WebView viene sempre impostato prefers-color-scheme secondo isLightTheme. Se isLightTheme è true o non specificato, allora prefers-color-scheme è light; altrimenti dark.

Ciò significa che se i contenuti web utilizzano prefers-color-scheme e i contenuti l'autore 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.

Inscurimento degli algoritmi

Per indicare casi in cui i contenuti web non utilizzano prefers-color-scheme, l'app può consentire a WebView, se necessario, di applicare algoritmicamente un tema ai contenuti web visualizzati.

Se la tua app utilizza l'impostazione a livello di app Forza Scuro a usare l'algoritmo applicare un tema scuro alla tua app, consulta la seguente sezione che descrive come: consentire il darkening algoritmico per i contenuti web con Force Dark.

Se la tua app non usa la funzionalità Scuro forza, in che modo l'app specifica quando consentire lo scurimento algoritmico in WebView dipende livello API target. Consulta le seguenti sezioni per le app destinate ad Android 13 o versioni successive e app che hanno come target Android 12 o versioni precedenti per maggiori dettagli.

Consenti il oscuramento algoritmico per i contenuti web con Force Dark

Se la tua app utilizza l'impostazione a livello di app Scuro forzato: si applica WebView oscuramento algoritmico dei contenuti web se si verificano 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 usa prefers-color-scheme.
Per le app che hanno come target Android 12 (livello API 32) o versioni precedenti: l'app ha impostato Impostazione forceDarkMode di WebView a FORCE_DARK_AUTO e ha impostato la strategia Force Dark DARK_STRATEGY_USER_AGENT_DARKENING_ONLY

WebView e tutti gli elementi padre possono consentire il oscuramento forzato utilizzando View.setForceDarkAllowed() Il valore predefinito viene recuperato dall'attributo setForceDarkAllowed() dell' Tema Android, che deve essere impostato anche su true.

La modalità Forza Buio viene fornita principalmente per la compatibilità con le versioni precedenti nelle app che non forniscono un tema scuro personalizzato. Se la tua app usa la modalità Scuro forza, ti consigliamo aggiunta di 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 che hanno come target Android 13 (livello API 33) o versioni successive, utilizza AndroidX setAlgorithmicDarkeningAllowed() e passare true per specificare che un componente WebView deve consentire oscuramento. Questo metodo è compatibile con le versioni precedenti di Android e versioni successive.

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

I contenuti web non utilizzano prefers-color-scheme.
L'autore dei 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 inferiore, utilizza FORCE_DARK_ON per consentire il darkening algoritmico.

Usa FORCE_DARK_ON insieme a FORCE_DARK_OFF se la tua app offre 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 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 di modifiche alle preferenze di sistema, dovrebbe ascoltare esplicitamente le modifiche apportate al tema e applicarle a WebView con FORCE_DARK_ON e FORCE_DARK_OFF stati.

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

Personalizza la gestione del tema scuro

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

Se usi l'API, la tua app può usare sia lo user agent che lo user agent oscuramento:

Oscuramento del tema web: gli sviluppatori web potrebbero applicare @media (prefers-color-scheme: dark) per controllare l'aspetto della pagina web in modalità Buio. WebView esegue il rendering dei contenuti in base a queste impostazioni. Per ulteriori informazioni su tema web, controlla specifica.
Scurimento dello user agent: il componente WebView inverte automaticamente i colori del web. . Se utilizzi il oscuramento dello user agent, La query @media (prefers-color-scheme: dark) restituisce false.

Per scegliere tra le due strategie, utilizza l'API seguente:

Kotlin

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

Java

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

Le opzioni delle strategie supportate sono:

DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING: Questa è l'opzione predefinita. Sebbene la maggior parte dei browser Tag <meta name="color-scheme" content="dark light"> come facoltativo, Android La modalità predefinita di WebView richiede che il meta tag rispetti le prefers-color-scheme query supporti. Puoi utilizzare i componenti WebView con DARK_STRATEGY_WEB_THEME_DARKENING_ONLY in questo caso WebView applica sempre query supporti anche se il tag omesso.

Tuttavia, consigliamo agli sviluppatori web di aggiungere <meta name="color-scheme" content="dark light"> al proprio sito web per assicurati che i contenuti vengano visualizzati correttamente nei componenti WebView con configurazione predefinita.
DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: Detto "user-agent darkening", WebView ignora gli eventuali oscuramenti delle pagine web o oscura automaticamente.

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

Per un esempio di tema scuro applicato, consulta le Demo di WebView su GitHub