Webinhalte in WebView abdunkeln

Ab Android 10 kann eine App ein dunkles Design unterstützen und je nach Systemdesign automatisch zwischen dem hellen und dem dunklen App-Design wechseln. Für Webinhalte in WebView kann auch der helle, der dunkle oder der Standardstil verwendet werden, um sie an das aktuelle App-Design anzupassen.

Das Verhalten von WebView interagiert mit den Webstandards prefers-color-scheme und color-scheme. Wenn du die Webinhalte erstellst, die in deiner App in WebView angezeigt werden sollen, solltest du nach Möglichkeit ein dunkles Design für deine Website definieren und prefers-color-scheme implementieren, damit WebView das Design der Webinhalte an das Design deiner App anpassen kann.

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

Stil für Content-Autor

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

Wenn also die Webinhalte prefers-color-scheme verwenden und der Autor dies zulässt, wird das vom Autor definierte helle oder dunkle Design immer automatisch auf die Webinhalte angewendet, das dem Design der App entspricht.

Algorithmische Verdunkelung

In Fällen, in denen prefers-color-scheme nicht für Webinhalte verwendet wird, kann WebView bei Bedarf ein dunkles Design algorithmisch auf die von ihm gerenderten Webinhalte angewendet werden.

Wenn Ihre App Dunkles Design erzwingen auf App-Ebene verwendet, um ein dunkles Design auf App-Ebene anzuwenden, lesen Sie im folgenden Abschnitt, wie Sie Mit der Funktion „Dunkles Design erzwingen“ die algorithmische Abdunkelung für Webinhalte zulassen.

Wenn in Ihrer App die Funktion „Dunkles Filtern erzwingen“ nicht verwendet wird, hängt es vom Ziel-API-Level Ihrer App ab, wie in Ihrer App angegeben wird, wann die algorithmische Verdunkelung in WebView zugelassen wird. Weitere Informationen finden Sie in den folgenden Abschnitten zu Apps für Android 13 oder höher und Apps für Android 12 oder niedriger.

Algorithmusbasierte Abdunkelung für Webinhalte mit „Dunkles Design erzwingen“ zulassen

Wenn für Ihre App die Option Force Dark (Dunkel erzwingen) auf App-Ebene verwendet wird, wendet WebView die algorithmische Abdunkelung auf Webinhalte an, wenn die folgenden Bedingungen erfüllt sind:

• Für WebView und die übergeordneten Elemente kann „Force Dark“ aktiviert werden.
• Das aktuelle Aktivitätsdesign ist als „Hell“ gekennzeichnet und isLightTheme ist auf true gesetzt.
• Der Autor des Webinhalts deaktiviert die Verdunkelung nicht explizit.
• Bei Apps, die auf Android 13 (API-Level 33) oder höher ausgerichtet sind, wird prefers-color-scheme nicht in den Webinhalten verwendet.
• Für Apps, die auf Android 12 (API-Level 32) oder niedriger ausgerichtet sind: Für die App wurde die forceDarkMode-Einstellung von WebView auf FORCE_DARK_AUTO und die Strategie „Force Dark“ auf DARK_STRATEGY_USER_AGENT_DARKENING_ONLY gesetzt.

WebView und alle übergeordneten Elemente können das Erzwingen der Dunkelheit mithilfe von View.setForceDarkAllowed() zulassen. Der Standardwert wird aus dem Attribut setForceDarkAllowed() des Android-Designs übernommen, das ebenfalls auf true gesetzt sein muss.

Die Funktion „Dunklen Modus erzwingen“ wird hauptsächlich für die Abwärtskompatibilität in Apps bereitgestellt, die kein eigenes dunkles Design bereitstellen. Wenn Ihre App die Option „Dunkles Design erzwingen“ verwendet, empfehlen wir, ein dunkles Design zu unterstützen.

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

Für Apps, die nicht auf App-Ebene „Force Dark“ verwenden und auf Android 13 (API-Level 33) oder höher ausgerichtet sind, verwende die AndroidX-Methode setAlgorithmicDarkeningAllowed() und übergib true, um anzugeben, dass ein WebView die algorithmische Dunkelung zulassen soll. Diese Methode ist mit früheren Android-Versionen abwärtskompatibel.

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

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

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

Verwende FORCE_DARK_ON für Apps, die nicht „Force Dark“ auf App-Ebene verwenden und auf Android 12 (API-Level 32) oder niedriger ausgerichtet sind, um die algorithmische Abdunkelung zuzulassen.

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 ein-/ausschaltbares Element in der Benutzeroberfläche oder eine automatische zeitbasierte Auswahl.

Sie können prüfen, ob die Funktion unterstützt wird, indem Sie bei der Konfiguration Ihres WebView-Objekts (z. B. in Activity.onCreate) die folgenden Codezeilen einfügen:

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

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

Wenn Ihre App Änderungen an Systemeinstellungen erkennen muss, 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 Sie das Format des Designs ändern:

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

Verarbeitung des dunklen Designs anpassen

Sie können auch die ForceDarkStrategy API in AndroidX verwenden, um zu steuern, wie die Verdunkelung auf ein bestimmtes 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 Anwendung entweder die Webdesign-Abdunkelung oder die User-Agent-Abdunkelung verwenden:

• Webdesign-Abdunkelung: Webentwickler können die Darstellung von Webseiten im dunklen Modus mithilfe von @media (prefers-color-scheme: dark) steuern. WebView rendert Inhalte entsprechend diesen Einstellungen. Weitere Informationen zur Abdunkelung von Webthemen finden Sie in der Spezifikation.
• User-Agent-Abdunkelung: WebView kehrt automatisch die Farben der Webseite um. Wenn Sie die User-Agent-Abdunkelung 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:

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

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

Folgende Strategieoptionen werden unterstützt:

• DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING: Das ist die Standardoption. Während die meisten Browser das <meta name="color-scheme" content="dark light">-Tag als optional behandeln, ist für den Standardmodus von Android WebView das Meta-Tag erforderlich, um die prefers-color-scheme-Medienabfragen der Webseite zu berücksichtigen. Sie können WebViews mit dem Modus DARK_STRATEGY_WEB_THEME_DARKENING_ONLY verwenden. In diesem Fall wendet WebView immer Medienabfragen an, auch wenn das Tag weggelassen wird.

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

• DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: Diese Funktion wird als „User-Agent-Abdunkelung“ bezeichnet. WebView ignoriert die Abdunkelung von Webseiten und wendet die automatische Abdunkelung an.

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

Ein Beispiel für die Anwendung des dunklen Designs findest du in der WebView-Demo auf GitHub.