Webinhalte in WebView abdunkeln

Unter Android 10 und höher kann eine App ein dunkles Design unterstützen und automatisch zwischen hellen und dunklen App-Designs wechseln, je nach Systemdesign. Um dem aktuellen App-Design zu entsprechen, können Webinhalte in WebView auch mit hellem, dunklem oder Standard-Styling dargestellt werden.

Das Verhalten von WebView ist mit den Webstandards prefers-color-scheme und color-scheme kompatibel. Wenn Sie die Webinhalte, die Ihre App in WebView anzeigen soll, selbst erstellen, sollten Sie nach Möglichkeit ein dunkles Design für Ihre Website definieren und prefers-color-scheme implementieren, damit WebView das Design der Webinhalte an das Design Ihrer App anpassen kann.

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

App-Bedingungen Webinhalte, in denen prefers-color-scheme verwendet wird Webinhalte, in denen prefers-color-scheme nicht verwendet wird
Die App verwendet ein helles Design mit isLightTheme, das auf true festgelegt oder nicht festgelegt ist. WebView rendert die Inhalte mit dem hellen Design, das der Autor der Inhalte definiert hat. WebView rendert den Inhalt mit dem vom Autor des Inhalts definierten Standardstil.
Die App verwendet Funktion „Dunkles Design erzwingen“, um algorithmisch ein dunkles Design auf die App anzuwenden. WebView rendert die Inhalte mit dem dunklen Design, das der Autor der Inhalte definiert hat. Wenn der Autor der Inhalte dies zulässt, rendert WebView die Inhalte mit einem dunklen Design, das mithilfe eines Algorithmus generiert wird.
Die App verwendet ein dunkles Design mit isLightTheme auf false gesetzt und die App erlaubt nicht die algorithmische Abdunklung für WebView. WebView rendert die Inhalte mit dem dunklen Design, das vom Inhaltsautor definiert wurde. WebView rendert den Inhalt mit dem vom Autor des Inhalts definierten Standardstil.
Die App verwendet ein dunkles Design mit isLightTheme auf false gesetzt und die App erlaubt algorithmisches Abdunkeln für WebView. WebView rendert die Inhalte mit dem dunklen Design, das der Autor der Inhalte definiert hat. Wenn der Autor der Inhalte dies zulässt, rendert WebView die Inhalte mit einem dunklen Design, das mithilfe eines Algorithmus generiert wird.

Formatierung durch Content-Autoren

Das Attribut isLightTheme einer App gibt an, ob das Design der App hell oder dunkel ist. WebView legt prefers-color-scheme immer gemäß isLightTheme fest. Wenn isLightTheme gleich true ist oder nicht angegeben wird, ist prefers-color-scheme gleich light. Andernfalls ist prefers-color-scheme gleich dark.

Wenn im Webcontent prefers-color-scheme verwendet wird und der Autor des Inhalts dies zulässt, wird das vom Autor des Inhalts definierte helle oder dunkle Design immer automatisch auf den Webcontent angewendet, damit es mit dem Design der App übereinstimmt.

Algorithmisches Abdunkeln

Für Fälle, in denen Webinhalte nicht prefers-color-scheme verwenden, kann Ihre App WebView bei Bedarf erlauben, algorithmisch ein dunkles Design auf die gerenderten Webinhalte anzuwenden.

Wenn Ihre App die Funktion „Dunkles Design erzwingen“ auf App-Ebene verwendet, um algorithmisch ein dunkles Design auf Ihre App anzuwenden, lesen Sie den folgenden Abschnitt, in dem beschrieben wird, wie Sie algorithmisches Abdunkeln für Webinhalte mit der Funktion „Dunkles Design erzwingen“ zulassen.

Wenn Ihre App die Funktion „Dunkles Design erzwingen“ nicht verwendet, hängt es vom Ziel-API-Level Ihrer App ab, wie sie angibt, wann algorithmisches Abdunkeln in WebView zulässig ist. Weitere Informationen finden Sie in den folgenden Abschnitten für Apps, die auf Android 13 oder höher ausgerichtet sind und Apps, die auf Android 12 oder niedriger ausgerichtet sind.

Algorithmisches Abdunkeln für Webinhalte mit „Force Dark“ zulassen

Wenn in Ihrer App Funktion „Dunkles Design erzwingen“ auf App-Ebene verwendet wird, wendet WebView eine algorithmische Verdunkelung auf Webinhalte an, wenn die folgenden Bedingungen erfüllt sind:

  • Das WebView und seine übergeordneten Elemente lassen die Funktion „Dunkles Design erzwingen“ zu.
  • Das aktuelle Aktivitätsthema ist als hell markiert, wobei isLightTheme auf true festgelegt ist.
  • Der Autor der Webinhalte hat das Abdunkeln nicht explizit deaktiviert.
  • Bei Apps, die auf Android 13 (API‑Level 33) oder höher ausgerichtet sind, wird prefers-color-scheme nicht für Web-Inhalte verwendet.
  • Für Apps, die auf Android 12 (API‑Level 32) oder niedriger ausgerichtet sind: Die App hat die Einstellung forceDarkMode von WebView auf FORCE_DARK_AUTO und die Force Dark-Strategie auf DARK_STRATEGY_USER_AGENT_DARKENING_ONLY festgelegt.

WebView und alle übergeordneten Elemente können die Erzwingung des Dark Mode mit View.setForceDarkAllowed() zulassen. Der Standardwert wird aus dem Attribut setForceDarkAllowed() des Android-Themes übernommen, das ebenfalls auf true festgelegt werden muss.

Die Funktion „Dunkles Design erzwingen“ ist in erster Linie für die Abwärtskompatibilität in Apps vorgesehen, die kein eigenes dunkles Design bieten. Wenn Ihre App die Funktion „Dunkles Design erzwingen“ verwendet, empfehlen wir, Unterstützung für ein dunkles Design hinzuzufügen.

Algorithmisches Abdunkeln zulassen (Apps, die auf Android 13 oder höher ausgerichtet sind)

Verwenden Sie für Apps, die die Funktion „Dunkles Design erzwingen“ auf App-Ebene nicht verwenden und auf Android 13 (API-Level 33) oder höher ausgerichtet sind, die Jetpack Webkit-Methode setAlgorithmicDarkeningAllowed() und übergeben Sie true, um anzugeben, dass ein WebView die algorithmische Verdunkelung zulassen soll. Diese Methode ist abwärtskompatibel mit früheren Android-Versionen.

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

  • Die Webinhalte verwenden nicht prefers-color-scheme.
  • Der Autor der Webinhalte hat das Abdunkeln nicht explizit deaktiviert.

Algorithmisches Abdunkeln zulassen (Apps mit Ausrichtung auf Android 12 oder niedriger)

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

Verwenden Sie FORCE_DARK_ON zusammen mit FORCE_DARK_OFF, wenn Ihre App eine eigene Methode zum Wechseln zwischen hellen und dunklen Designs bietet, z. B. ein umschaltbares Element in der Benutzeroberfläche oder eine automatische zeitbasierte Auswahl.

Fügen Sie die folgenden Codezeilen an der Stelle ein, an der Sie Ihr WebView-Objekt konfigurieren, z. B. in Activity.onCreate, um zu prüfen, ob die Funktion unterstützt wird:

Kotlin

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

Java

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

Wenn Ihre App auf das Erkennen von Änderungen an den Systemeinstellungen angewiesen ist, sollte sie explizit auf Designänderungen warten und diese mit den Status FORCE_DARK_ON und FORCE_DARK_OFF auf WebView anwenden.

Das folgende Code-Snippet zeigt, wie das Format des Designs geändert wird:

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

Umgang mit dem dunklen Design anpassen

Sie können auch die ForceDarkStrategy API in der Jetpack-Bibliothek verwenden, um zu steuern, wie die Verdunkelung auf eine bestimmte WebView angewendet wird. Diese API ist nur anwendbar, wenn „Force Dark“ auf FORCE_DARK_ON oder FORCE_DARK_AUTO festgelegt ist.

Mit der API kann Ihre App entweder das Verdunkeln des Webdesigns oder das Verdunkeln des User-Agents verwenden:

  • Abdunklung von Webdesigns: Webentwickler können @media (prefers-color-scheme: dark) verwenden, um das Erscheinungsbild von Webseiten im Dunkelmodus zu steuern. WebView rendert Inhalte gemäß diesen Einstellungen. Weitere Informationen zum Abdunkeln von Webdesigns finden Sie in der Spezifikation.
  • User-Agent-Verdunkelung: Die Farben der Webseite werden in WebView automatisch invertiert. Wenn Sie die Verdunkelung des User-Agents verwenden, wird die @media (prefers-color-scheme: dark)-Abfrage 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(...);
}

Die unterstützten Strategieoptionen sind:

  • DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING: Dies ist die Standardoption. In den meisten Browsern ist das <meta name="color-scheme" content="dark light">-Tag optional. Im Standardmodus von Android WebView ist jedoch das Meta-Tag erforderlich, damit die Media-Anfragen der Webseite prefers-color-scheme berücksichtigt werden. Sie können WebViews im Modus DARK_STRATEGY_WEB_THEME_DARKENING_ONLY verwenden. In diesem Fall wendet WebView immer Media-Queries an, auch wenn das Tag ausgelassen wird.

    Wir empfehlen Webentwicklern jedoch, das <meta name="color-scheme" content="dark light">-Tag auf ihren Websites hinzuzufügen, damit Inhalte in WebViews mit der Standardkonfiguration korrekt gerendert werden.

  • DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: Bei dieser als „User-Agent Darkening“ bezeichneten Funktion wird das Darkening von Webseiten in WebView ignoriert und stattdessen automatisch ein Darkening angewendet.

Wenn in Ihrer App selbst erhobene Webinhalte angezeigt werden, die Sie mit der Media-Anfrage prefers-color-scheme angepasst haben, empfehlen wir, DARK_STRATEGY_WEB_THEME_DARKENING_ONLY dafür zu sorgen, dass WebView das benutzerdefinierte Design verwendet.

Ein Beispiel für das angewendete dunkle Design finden Sie in der WebView-Demo auf GitHub.