Webinhalte in WebView abdunkeln

Unter Android 10 und höher kann eine App ein dunkles Design unterstützen und automatisch je nach Systemdesign zwischen hellem und dunklem App-Design wechseln. Webinhalte in WebView können auch ein helles, dunkles oder Standard-Design verwenden, um dem aktuellen App-Design zu entsprechen.

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

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

Stil des Inhaltsautors

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

Wenn also prefers-color-scheme für den Webcontent verwendet wird und der Ersteller des Inhalts dies zulässt, wird das vom Ersteller des Inhalts definierte helle oder dunkle Design immer automatisch auf den Webcontent angewendet, um dem Design der App zu entsprechen.

Algorithmische Abdunkelung

Für den Fall, dass für Webinhalte kein prefers-color-scheme verwendet wird, kann Ihre App WebView erlauben, bei Bedarf algorithmisch ein dunkles Design auf die gerenderten Webinhalte anzuwenden.

Wenn in Ihrer App die Funktion Dunkles Design erzwingen auf App-Ebene verwendet wird, um ein dunkles Design algorithmisch anzuwenden, lesen Sie den folgenden Abschnitt, in dem beschrieben wird, wie Sie das algorithmische Verdunkeln von Webinhalten mit „Dunkles Design erzwingen“ zulassen.

Wenn Ihre Anwendung Force Dark nicht verwendet, hängt die Festlegung, wann die algorithmische Abdunkelung in WebView zugelassen wird, vom Ziel-API-Level Ihrer Anwendung ab. Weitere Informationen zu Apps, die auf Android 13 oder höher ausgerichtet sind, und zu Apps, die auf Android 12 oder niedriger ausgerichtet sind finden Sie in den folgenden Abschnitten.

Algorithmusbasierte Abdunkelung für Webinhalte mit Force Dark zulassen

Wenn Ihre App die Option Dark Mode erzwingen auf App-Ebene verwendet, wird Webcontent von WebView algorithmisch abgedunkelt, wenn die folgenden Bedingungen erfüllt sind:

• Das WebView und die übergeordneten Elemente ermöglichen „Force Dark“.
• Das aktuelle Aktivitätsdesign ist als hell gekennzeichnet und isLightTheme ist auf true gesetzt.
• Der Webinhaltsautor deaktiviert das Abdunkeln nicht ausdrücklich.
• Bei Apps, die auf Android 13 (API-Level 33) oder höher ausgerichtet sind, wird prefers-color-scheme nicht für Webinhalte verwendet.
• Für Apps, die auf Android 12 (API-Level 32) oder niedriger ausgerichtet sind: In der App ist die forceDarkMode-Einstellung von WebView auf FORCE_DARK_AUTO festgelegt und die Strategie für die erzwungene Dunkelmodus-Aktivierung auf DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

WebView und alle übergeordneten Elemente können das Erzwingen des dunklen Modus mit View.setForceDarkAllowed() zulassen. Der Standardwert wird aus dem Attribut setForceDarkAllowed() des Android-Designs übernommen, das ebenfalls auf true festgelegt werden muss.

Der erzwungene dunkle Modus dient hauptsächlich der Abwärtskompatibilität in Apps, die kein eigenes dunkles Design anbieten. Wenn deine App die Funktion „Dunkles Design erzwingen“ verwendet, empfehlen wir, Unterstützung für ein dunkles Design hinzuzufügen.

Algorithmische 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 33) oder höher ausgerichtet sind, verwenden Sie die AndroidX-Methode setAlgorithmicDarkeningAllowed() und übergeben Sie true, um anzugeben, dass eine WebView die algorithmische Verdunkelung zulassen soll. Diese Methode ist abwärtskompatibel mit früheren Android-Versionen.

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

• Für den Webinhalt wird prefers-color-scheme nicht verwendet.
• Der Webinhaltsautor deaktiviert das Abdunkeln nicht ausdrücklich.

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

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

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

Wenn Sie prüfen möchten, ob die Funktion unterstützt wird, fügen Sie die folgenden Codezeilen überall dort ein, wo Sie Ihr WebView-Objekt konfigurieren, z. B. in Activity.onCreate:

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

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

Wenn Ihre App Änderungen an den Systemeinstellungen erkennen muss, sollte sie explizit auf Designänderungen achten und diese mit den Status FORCE_DARK_ON und FORCE_DARK_OFF auf WebView anwenden.

Das folgende Code-Snippet zeigt, wie das Themenformat geändert wird:

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 festzulegen, wie die Verdunkelung auf eine bestimmte WebView angewendet wird. Diese API ist nur gültig, wenn „dark“ auf FORCE_DARK_ON oder FORCE_DARK_AUTO gesetzt ist.

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

• Abdunkeln des Web-Designs: Webentwickler können @media (prefers-color-scheme: dark) anwenden, um das Erscheinungsbild der Webseite im dunklen Modus zu steuern. WebView rendert Inhalte gemäß diesen Einstellungen. Weitere Informationen zum Abdunkeln von Webthemen finden Sie in der Spezifikation.
• Abdunkelung des User-Agents: Die WebView invertiert automatisch die Farben der Webseite. Wenn Sie die Verdunkelung des User-Agents verwenden, wird für die @media (prefers-color-scheme: dark)-Abfrage false zurückgegeben.

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(...);
}

Die unterstützten Strategieoptionen sind:

• DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING: Dies ist die Standardoption. Während die meisten Browser das <meta name="color-scheme" content="dark light">-Tag als optional behandeln, ist es im Standardmodus von Android WebView erforderlich, damit die <meta name="color-scheme" content="dark light">-Medienabfragen der Webseite berücksichtigt werden.prefers-color-scheme Sie können WebViews mit dem Modus DARK_STRATEGY_WEB_THEME_DARKENING_ONLY verwenden. In diesem Fall werden von WebView immer Mediaabfragen angewendet, auch wenn das Tag weggelassen wird.

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

• DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: Diese Methode, die als „User-Agent-Abdunkelung“ bezeichnet wird, ignoriert die WebView-Abdunkelung und wendet eine automatische Abdunkelung an.

Wenn Ihre App selbst erstellte Webinhalte zeigt, die Sie mit der prefers-color-scheme-Medienabfrage angepasst haben, sollten Sie dafür sorgen, dass WebView das benutzerdefinierte Design verwendet.DARK_STRATEGY_WEB_THEME_DARKENING_ONLY

Ein Beispiel für ein dunkles Design finden Sie in der WebView-Demo auf GitHub.