Webinhalte in WebView abdunkeln

Ab Android 10 unterstützt eine App Dunkles Design, das sich automatisch ändert je nach Systemdesign zwischen hellem und dunklem App-Design zu wechseln. Um den Aktuelles App-Design, Webinhalte in WebView kann auch einen hellen, dunklen oder Standardstil verwenden.

Das Verhalten von WebView interagiert mit dem prefers-color-scheme und color-scheme Webstandards. Wenn Sie die Webinhalte, die Sie verwenden möchten, eure App in WebView angezeigt werden soll, solltet ihr ein dunkles Design für eure Website und prefers-color-scheme implementieren, damit WebView die zum Design Ihrer App hinzufügen.

In der folgenden Tabelle wird beschrieben, wie WebView Webinhalte in Ihrer App rendert. je nach Stil der Webinhalte und den Bedingungen Ihrer App:

Bedingungen für Apps Webinhalte, die prefers-color-scheme verwenden Webinhalte, die nicht prefers-color-scheme verwenden
Die App verwendet ein helles Design mit isLightTheme auf true festgelegt oder nicht festgelegt. WebView rendert die Inhalte mit dem hellen Design, vom Autor des Inhalts definiert wurde. WebView rendert den Inhalt mit dem Standardstil, der vom Inhaltsverfasser.
App verwendet Dunkles Design erzwingen bis dunkles Design mithilfe eines Algorithmus anwenden in der App. WebView rendert die Inhalte im dunklen Design, vom Autor des Inhalts definiert wurde. Sofern der Autor des Inhalts dies zulässt, rendert WebView den Inhalt mit einem dunkles Design, das mit einem Algorithmus generiert wird.
App verwendet dunkles Design mit isLightTheme auf false festgelegt ist und die App keine algorithmischen für WebView zu verdunkeln. WebView rendert die Inhalte im dunklen Design, vom Autor des Inhalts definiert wurde. WebView rendert den Inhalt mit dem Standardstil, der vom Inhaltsverfasser.
App verwendet dunkles Design mit isLightTheme auf false festgelegt ist und die App erlaubt Algorithmische Abdunkelung für WebView. WebView rendert die Inhalte im dunklen Design, vom Autor des Inhalts definiert wurde. Sofern der Autor des Inhalts dies zulässt, rendert WebView den Inhalt mit einem dunkles Design, das mit einem Algorithmus generiert wird.

Stil des Autors von Inhalten

Die Attribut isLightTheme gibt an, ob das Design der App hell oder dunkel ist. WebView legt immer fest prefers-color-scheme laut isLightTheme. Wenn isLightTheme den Wert true hat nicht angegeben ist, dann ist prefers-color-scheme light. Andernfalls ist es dark

Wenn für den Webinhalt also prefers-color-scheme verwendet wird und der Inhalt Autor erlaubt, das helle oder dunkle Design, das vom Autor des Inhalts festgelegt wurde wird immer automatisch auf den Webinhalt angewendet, damit er zum Design der App passt.

Algorithmische Verdunkelung

Um Fälle abzudecken, in denen Webinhalte nicht verwendet werden, prefers-color-scheme, kann WebView bei Bedarf mithilfe von Algorithmen ein Darknet in Webinhalten, die gerendert werden.

Wenn Ihre App die App-Ebene verwendet Dunkles Design erzwingen, um Algorithmen zu aktivieren ein dunkles Design auf Ihre App anwenden. Im folgenden Abschnitt wird beschrieben, wie Sie Ermöglichen Sie die algorithmische Abdunkelung von Webinhalten mit Force Dark.

Wenn deine App Force Dark nicht verwendet, legt sie fest, wann sie Benachrichtigungen für die algorithmische Abdunkelung in WebView Ziel-API-Level an. Weitere Informationen zu Apps, die auf Android 13 oder höher ausgerichtet sind und Apps für Android 12 oder niedriger.

Algorithmische Abdunkelung für Webinhalte mit Force Dark zulassen

Wenn Ihre App die App-Ebene verwendet Dunkles Design erzwingen, WebView wird angewendet algorithmische Verdunkelung auf Webinhalte, wenn die folgenden Bedingungen erfüllt sind:

  • Das WebView und die übergeordneten Elemente ermöglichen „Force Dark“.
  • Das aktuelle Aktivitätsdesign ist als hell markiert mit isLightTheme festgelegt auf true.
  • Der Autor von Webinhalten deaktiviert die Verdunkelung nicht explizit.
  • Bei Apps, die auf Android 13 (API-Level 33) oder höher ausgerichtet sind, werden die Webinhalte verwendet prefers-color-scheme nicht.
  • Für Apps, die auf Android 12 (API-Level 32) oder niedriger ausgerichtet sind, wurde für die App Folgendes festgelegt: forceDarkMode-Einstellung von WebView bis FORCE_DARK_AUTO und hat die Strategie „Force Dark“ DARK_STRATEGY_USER_AGENT_DARKENING_ONLY

WebView und alle übergeordneten Elemente können die Erzwingung der Dunkelheit zulassen mit View.setForceDarkAllowed() Der Standardwert wird aus dem Attribut setForceDarkAllowed() der Android-Design, das ebenfalls auf true festgelegt sein muss.

Die Option „Dunklen Modus erzwingen“ dient hauptsächlich zur Abwärtskompatibilität in Apps, die kein eigenes dunkles Design bereitstellen. Wenn deine App Force Dark nutzt, empfehlen wir, Ein dunkles Design wird unterstützt.

Algorithmusbasierte Verdunkelung zulassen (Apps, die auf Android 13 oder höher ausgerichtet sind)

Für Apps, die nicht „Force Dark“ auf App-Ebene verwenden und auf Android 13 (API-Level) ausgerichtet sind 33) oder höher müssen Sie AndroidX setAlgorithmicDarkeningAllowed() und übergeben Sie true, um anzugeben, dass eine WebView algorithmische und verdunkelt sich. Diese Methode ist mit der vorherigen Android-Version kompatibel Versionen.

WebView wendet dann die algorithmische Abdunkelung an, wenn die folgenden Bedingungen erfüllt sind:

  • Für den Webinhalt wird prefers-color-scheme nicht verwendet.
  • Der Autor von Webinhalten deaktiviert die Verdunkelung nicht explizit.

Algorithmusbasierte Verdunkelung zulassen (Apps, die auf Android 12 oder niedriger ausgerichtet sind)

Für Apps, die nicht „Force Dark“ auf App-Ebene verwenden und auf Android 12 (API-Level) ausgerichtet sind 32) oder niedriger, verwenden Sie FORCE_DARK_ON um eine algorithmische Verdunkelung zu ermöglichen.

FORCE_DARK_ON zusammen mit FORCE_DARK_OFF Falls Ihre App eine eigene Methode zum Wechseln zwischen hellem und dunklem Design bietet, wie ein ein-/ausschaltbares Element in der Benutzeroberfläche oder eine automatische zeitbasierte Auswahl.

Fügen Sie die folgenden Codezeilen hinzu, um zu überprüfen, ob die Funktion unterstützt wird überall dort, wo Sie Ihr WebView-Objekt konfigurieren, z. B. in Activity.onCreate:

Kotlin

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

Java

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

Wenn Ihre App Änderungen an den Systemeinstellungen erkennt, sollte sie Designänderungen explizit überwachen und diese mit FORCE_DARK_ON und FORCE_DARK_OFF.

Das folgende Code-Snippet zeigt, wie Sie das Designformat ändern:

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

Verarbeitung des dunklen Designs anpassen

Sie können auch die ForceDarkStrategy API in AndroidX steuern, wie die Verdunkelung auf eine bestimmte WebView angewendet wird. Diese API ist gilt nur, wenn „Dunkles dunkles erzwingen“ auf FORCE_DARK_ON oder FORCE_DARK_AUTO festgelegt ist.

Mit der API kann Ihre App entweder die Webdesign-Abdunkelung oder den User-Agent verwenden. Verdunkelung:

  • Webdesigns dunkler: Webentwickler können sich Mit @media (prefers-color-scheme: dark) die Darstellung von Webseiten in dunkler Modus. WebView rendert Inhalte gemäß diesen Einstellungen. Weitere Informationen Web-Design abgedunkelt werden, siehe Spezifikation.
  • User-Agent-Abdunkelung: WebView kehrt die Webfarben automatisch um. Seite. Wenn Sie die User-Agent-Abdunkelung verwenden, Die Abfrage @media (prefers-color-scheme: dark) wird als false ausgewertet.

Verwenden Sie die folgende API, um zwischen den beiden Strategien zu wählen:

Kotlin

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

Java

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

Folgende Strategieoptionen werden unterstützt:

  • <ph type="x-smartling-placeholder"></ph> DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING: Das ist die Standardoption. Die meisten Browser behandeln <meta name="color-scheme" content="dark light">-Tag als optional, Android Im Standardmodus von WebView muss das Meta-Tag die prefers-color-scheme Medienabfragen. Sie können WebViews mit <ph type="x-smartling-placeholder"></ph> DARK_STRATEGY_WEB_THEME_DARKENING_ONLY. In diesem Fall wendet WebView immer Medienabfragen an, auch wenn das Tag ausgelassen.

    Wir empfehlen Webentwicklern jedoch, <meta name="color-scheme" content="dark light"> auf ihren Websites taggen, um sicherzustellen, dass Inhalte in WebViews mit der Standardkonfiguration.

  • <ph type="x-smartling-placeholder"></ph> DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: Die Bezeichnung „User-Agent-Abdunkelung“ ignoriert das WebView alle Verdunkelungs- und wendet eine automatische Verdunkelung an.

Wenn in Ihrer App eigene Webinhalte angezeigt werden, die Sie mit der prefers-color-scheme Medienabfrage, wir empfehlen DARK_STRATEGY_WEB_THEME_DARKENING_ONLY damit WebView das benutzerdefinierte Design verwendet.

Ein Beispiel für das dunkle Design findest du in der WebView-Demo auf GitHub