Przyciemnianie treści z internetu w komponencie WebView

Na Androidzie 10 i nowszych aplikacja może obsługiwać ciemny motyw i automatycznie przełączać się między jasnym a ciemnym motywem w zależności od motywu systemu. Aby pasować do bieżącego motywu aplikacji, treści z internetu w WebView mogą też mieć styl jasny, ciemny lub domyślny.

Działania WebView są zgodne ze standardami prefers-color-scheme i color-scheme. Jeśli tworzysz treści internetowe, które mają być wyświetlane w komponencie WebView, w miarę możliwości zdefiniuj ciemny motyw dla swojej witryny i wprowadź prefers-color-scheme, aby komponent WebView mógł dopasować motyw treści internetowych do motywu aplikacji.

W tabeli poniżej opisano, jak WebView renderuje treści internetowe w aplikacji w zależności od ich stylizacji i warunków aplikacji:

Stylizacja autora treści

Atrybut aplikacji isLightTheme wskazuje, czy motyw aplikacji jest jasny czy ciemny. WebView zawsze ustawia prefers-color-scheme zgodnie z wartością isLightTheme. Jeśli isLightTheme ma wartość true lub nie jest określona, prefers-color-scheme to light. W przeciwnym razie ma wartość dark.

Oznacza to, że jeśli treści internetowe używają prefers-color-scheme, a twórca treści na to zezwala, jasny lub ciemny motyw zdefiniowany przez twórcę treści jest zawsze automatycznie stosowany do treści internetowych, aby pasował do motywu aplikacji.

Algorytm ściemniania

W przypadku treści internetowych, które nie używają prefers-color-scheme, aplikacja może zezwolić komponentowi WebView, aby w razie potrzeby zastosował algorytmicznie ciemny motyw do renderowanych treści.

Jeśli Twoja aplikacja korzysta z trybu Force Dark na poziomie aplikacji do algorytmicznego stosowania ciemnego motywu, przeczytaj sekcję poniżej, aby dowiedzieć się, jak zezwolić na algorytmiczne przyciemnianie treści z internetu za pomocą opcji Wymuś tryb ciemny.

Jeśli Twoja aplikacja nie korzysta z opcji wymuszania ciemnego motywu, sposób, w jaki określa ona, kiedy zezwolić na automatyczne przyciemnianie w WebView, zależy od docelowego poziomu interfejsu API aplikacji. W następnych sekcjach znajdziesz szczegółowe informacje o aplikacjach kierowanych na Androida 13 lub nowszego oraz aplikacjach kierowanych na Androida 12 lub starszego.

Zezwalanie na algorytmiczne przyciemnianie treści internetowych za pomocą wymuszania trybu ciemnego

Jeśli aplikacja używa wymuszania ciemnego motywu na poziomie aplikacji, WebView stosuje algorytmiczne przyciemnianie treści internetowych, jeśli są spełnione te warunki:

• WebView i jego elementy nadrzędne umożliwiają stosowanie trybu ciemnego.
• Bieżący motyw aktywności jest oznaczony jako jasny, a isLightTheme ma wartość true.
• Autor treści internetowych nie wyłącza wprost przyciemnienia.
• W przypadku aplikacji kierowanych na Androida 13 (poziom interfejsu API 33) lub nowszego w treściach z internetu nie jest używany prefers-color-scheme.
• Aplikacje kierowane na Androida 12 (poziom API 32) lub starszego: ustawienie forceDarkMode w WebView zostało ustawione na FORCE_DARK_AUTO, a ustawienie wymuszania ciemnego motywu na DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

Komponent WebView i wszystkie jego elementy nadrzędne mogą zezwalać na wymuszanie trybu ciemnego za pomocą interfejsu View.setForceDarkAllowed(). Wartość domyślna jest pobierana z atrybutu setForceDarkAllowed() motywu Androida, który musi być również ustawiony na true.

Tryb ciemny jest udostępniany głównie w celu zapewnienia zgodności wstecznej w aplikacjach, które nie mają własnego ciemnego motywu. Jeśli Twoja aplikacja używa trybu ciemnego, zalecamy dodanie obsługi ciemnego motywu.

Zezwalanie na algorytmiczne przyciemnianie (aplikacje kierowane na Androida 13 lub nowszego)

W przypadku aplikacji, które nie korzystają z funkcji Force Dark na poziomie aplikacji i są kierowane na Androida 13 (poziom interfejsu API 33) lub nowszego, użyj metody AndroidX setAlgorithmicDarkeningAllowed() i przekaż wartość true, aby określić, że komponent WebView powinien umożliwiać algorytm przyciemnianie. Ta metoda jest zgodna wstecznie z poprzednimi wersjami Androida.

WebView stosuje następnie algorytmiczne przyciemnianie, jeśli są spełnione te warunki:

• Treści internetowe nie używają prefers-color-scheme.
• Autor treści internetowych nie wyłącza wyraźnie przyciemnienia.

Zezwalanie na algorytmiczne przyciemnianie (aplikacje kierowane na Androida 12 lub niższego)

W przypadku aplikacji, które nie korzystają z funkcji Force Dark na poziomie aplikacji i są kierowane na Androida 12 (poziom interfejsu API 32) lub starszego, użyj opcji FORCE_DARK_ON, aby umożliwić algorytm ściemniania.

Używaj FORCE_DARK_ON w połączeniu z FORCE_DARK_OFF, jeśli Twoja aplikacja udostępnia własną metodę przełączania się między motywem jasnym i ciemnym, na przykład element, który można przełączać w interfejsie, lub automatyczny wybór na podstawie czasu.

Aby sprawdzić, czy funkcja jest obsługiwana, dodaj te wiersze kodu wszędzie tam, gdzie konfigurujesz obiekt WebView, np. w Activity.onCreate:

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

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

Jeśli aplikacja ma wykrywać zmiany ustawień systemu, powinna wyraźnie sprawdzać zmiany motywu i stosować je w WebView za pomocą stanów FORCE_DARK_ON i FORCE_DARK_OFF.

Ten fragment kodu pokazuje, jak zmienić format motywu:

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

Dostosowywanie obsługi ciemnego motywu

Możesz też użyć interfejsu ForceDarkStrategy API w AndroidX, aby kontrolować sposób ciemnienia danego WebView. Ten interfejs API jest dostępny tylko wtedy, gdy ustawienie wymuszania ciemnego motywu ma wartość FORCE_DARK_ON lub FORCE_DARK_AUTO.

Dzięki interfejsowi API aplikacja może stosować ciemny motyw lub ciemny interfejs klienta użytkownika:

• Ciemnienie motywu witryny: deweloperzy witryn mogą stosować @media (prefers-color-scheme: dark), aby kontrolować wygląd strony w trybie ciemnym. WebView renderuje treści zgodnie z tymi ustawieniami. Więcej informacji o przyciemnianiu motywów internetowych znajdziesz w specyfikacji.
• Przyciemnienie klienta użytkownika: komponent WebView automatycznie odwraca kolory na stronie internetowej. Jeśli używasz przyciemniania klienta użytkownika, zapytanie @media (prefers-color-scheme: dark) zostanie przekształcone w false.

Aby wybrać jedną z tych strategii, użyj tego interfejsu API:

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

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

Obsługiwane opcje strategii:

• DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING: to opcja domyślna. Chociaż większość przeglądarek traktuje tag <meta name="color-scheme" content="dark light"> jako opcjonalny, domyślny tryb WebView w Androidzie wymaga, aby metatag uwzględniał zapytania o multimedia prefers-color-scheme strony internetowej. Komponenty WebView możesz używać w trybie DARK_STRATEGY_WEB_THEME_DARKENING_ONLY, w którym WebView zawsze stosuje zapytania o multimedia, nawet jeśli tag jest pominięty.

  Zalecamy jednak, aby deweloperzy stron internetowych dodawali do nich tag <meta name="color-scheme" content="dark light">, aby zapewnić prawidłowe renderowanie treści w WebView w domyślnej konfiguracji.

• DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: Funkcja „przyciemnianie user-agenta”: WebView ignoruje przyciemnianie strony internetowej i automatycznie stosuje przyciemnianie.

Jeśli Twoja aplikacja wyświetla własne treści internetowe dostosowane za pomocą zapytania o media prefers-color-scheme, zalecamy użycie DARK_STRATEGY_WEB_THEME_DARKENING_ONLY, aby mieć pewność, że WebView używa motywu niestandardowego.

Przykład zastosowania ciemnego motywu znajdziesz w demo WebView na GitHubie.