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 aplikacji w zależności od motywu systemu. Aby dopasować się do bieżącego motywu aplikacji, treści internetowe w WebView mogą też korzystać z jasnego, ciemnego lub domyślnego stylu.

Działanie komponentu WebView jest zgodne ze standardami internetowymi prefers-color-scheme i  color-scheme. Jeśli to możliwe, a jesteś autorem treści internetowych, które mają być wyświetlane w aplikacji w komponencie WebView, zdefiniuj ciemny motyw witryny i wdroż prefers-color-scheme, aby komponent WebView mógł dopasować motyw treści internetowych do motywu aplikacji.

Tabela poniżej opisuje, jak WebView renderuje treści internetowe w aplikacji w zależności od stylu treści internetowych i warunków aplikacji:

Warunki aplikacji Treści z internetu, które korzystają z prefers-color-scheme Treści internetowe, które nie używają prefers-color-scheme
Aplikacja używa jasnego motywu, a wartość parametru isLightTheme jest ustawiona na true lub nie jest ustawiona. WebView renderuje treści w jasnym motywie, który zdefiniował autor treści. WebView renderuje treści z domyślnym stylem określonym przez autora treści.
Aplikacja używa wymuszonego trybu ciemnego, aby algorytmicznie zastosować ciemny motyw. WebView renderuje treści w ciemnym motywie, który zdefiniował autor treści. Jeśli autor treści na to zezwoli, WebView renderuje treści w ciemnym motywie wygenerowanym za pomocą algorytmu.
Aplikacja używa ciemnego motywu z ustawieniem isLightTheme na false i nie zezwala na algorytmiczne przyciemnianie komponentu WebView. WebView renderuje treści w ciemnym motywie, który zdefiniował autor treści. WebView renderuje treści z domyślnym stylem określonym przez autora treści.
Aplikacja używa ciemnego motywu, w którym wartość isLightTheme jest ustawiona na false, a aplikacja umożliwia algorytmiczne przyciemnianie w WebView. WebView renderuje treści w ciemnym motywie, który zdefiniował autor treści. Jeśli autor treści na to zezwoli, WebView renderuje treści w ciemnym motywie wygenerowanym za pomocą algorytmu.

Stylizacja autora treści

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

Oznacza to, że jeśli treść internetowa używa prefers-color-scheme i autor treści na to zezwala, do treści internetowej zawsze automatycznie stosowany jest jasny lub ciemny motyw zdefiniowany przez autora treści, aby pasował do motywu aplikacji.

Algorytmiczne przyciemnianie

W przypadku treści internetowych, które nie korzystają z prefers-color-scheme, aplikacja może w razie potrzeby zezwolić komponentowi WebView na algorytmiczne stosowanie ciemnego motywu do renderowanych treści internetowych.

Jeśli aplikacja używa funkcji wymuszania trybu ciemnego na poziomie aplikacji, aby algorytmicznie zastosować ciemny motyw, zapoznaj się z sekcją poniżej, która opisuje, jak zezwolić na algorytmiczne przyciemnianie treści internetowych za pomocą funkcji wymuszania trybu ciemnego.

Jeśli aplikacja nie korzysta z wymuszania trybu ciemnego, sposób określania, kiedy zezwolić na algorytmiczne przyciemnianie w komponencie WebView, zależy od docelowego poziomu interfejsu API aplikacji. Szczegółowe informacje znajdziesz w sekcjach dotyczących aplikacji kierowanych na Androida 13 lub nowszego oraz aplikacji kierowanych na Androida 12 lub starszego.

Zezwalaj na algorytmiczne przyciemnianie treści internetowych w przypadku wymuszonego trybu ciemnego

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

  • Element WebView i jego elementy nadrzędne zezwalają na wymuszanie trybu ciemnego.
  • Bieżący motyw aktywności jest oznaczony jako jasny, a wartość parametru isLightTheme jest ustawiona na true.
  • Autor treści internetowych nie wyłączył wyraźnie przyciemniania.
  • W przypadku aplikacji kierowanych na Androida 13 (API na poziomie 33) lub nowszego treści internetowe nie używają prefers-color-scheme.
  • W przypadku aplikacji kierowanych na Androida 12 (poziom API 32) lub starszego: aplikacja ma ustawienie forceDarkMode komponentu WebView ustawione na FORCE_DARK_AUTO i strategię wymuszania trybu ciemnego ustawioną na DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

WebView i wszystkie jego elementy nadrzędne mogą zezwalać na wymuszone ciemne tło za pomocą kodu View.setForceDarkAllowed(). Wartość domyślna jest pobierana z atrybutu setForceDarkAllowed() motywu Androida, który również musi być ustawiony na true.

Wymuszony tryb ciemny jest przeznaczony głównie do zapewnienia zgodności wstecznej w aplikacjach, które nie mają własnego ciemnego motywu. Jeśli Twoja aplikacja korzysta z wymuszonego 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 używają wymuszonego trybu ciemnego na poziomie aplikacji i są kierowane na Androida 13 (API na poziomie 33) lub nowszego, użyj metody Jetpack WebkitsetAlgorithmicDarkeningAllowed() i przekaż wartość true, aby określić, że element WebView powinien zezwalać na algorytmiczne przyciemnianie. Ta metoda jest wstecznie zgodna z poprzednimi wersjami Androida.

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

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

Zezwalaj na algorytmiczne przyciemnianie (aplikacje kierowane na Androida 12 lub starszego)

W przypadku aplikacji, które nie używają wymuszonego trybu ciemnego na poziomie aplikacji i są kierowane na Androida 12 (poziom API 32) lub starszego, użyj FORCE_DARK_ON, aby włączyć algorytmiczne przyciemnianie.

Użyj FORCE_DARK_ON razem z FORCE_DARK_OFF, jeśli aplikacja udostępnia własną metodę przełączania między jasnym a ciemnym motywem, np. element przełączany w interfejsie lub automatyczny wybór na podstawie czasu.

Aby sprawdzić, czy ta funkcja jest obsługiwana, dodaj te wiersze kodu w miejscu, w którym konfigurujesz obiekt WebView, np. w pliku Activity.onCreate:

Kotlin

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

Java

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

Jeśli Twoja aplikacja opiera się na wykrywaniu zmian w ustawieniach systemowych, powinna wyraźnie nasłuchiwać zmian motywu i stosować je w WebView w stanach FORCE_DARK_ON i FORCE_DARK_OFF.

Poniższy fragment kodu pokazuje, jak zmienić format motywu:

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

Dostosowywanie obsługi ciemnego motywu

Możesz też użyć interfejsu ForceDarkStrategy API w bibliotece Jetpack, aby określić, jak przyciemnianie ma być stosowane w przypadku danego widoku WebView. Ten interfejs API ma zastosowanie tylko wtedy, gdy przyciemnianie jest ustawione na FORCE_DARK_ON lub FORCE_DARK_AUTO.

Za pomocą interfejsu API aplikacja może korzystać z przyciemniania motywu internetowego lub przyciemniania przez klienta użytkownika:

  • Przyciemnianie motywu strony internetowej: deweloperzy stron internetowych 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 motywu strony internetowej znajdziesz w specyfikacji.
  • Przyciemnianie za pomocą user-agenta: WebView automatycznie odwraca kolory strony internetowej. Jeśli używasz zaciemniania klienta użytkownika, zapytanie @media (prefers-color-scheme: dark) zostanie przekształcone w false.

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

Kotlin

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

Java

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

Obsługiwane opcje strategii to:

  • DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING: to opcja domyślna. Większość przeglądarek traktuje tag <meta name="color-scheme" content="dark light"> jako opcjonalny, ale domyślny tryb Androida WebView wymaga, aby tag meta uwzględniał zapytania o media prefers-color-scheme na stronie internetowej. Możesz używać widoków WebView w trybie DARK_STRATEGY_WEB_THEME_DARKENING_ONLY, w którym to przypadku widok WebView zawsze stosuje zapytania o media, nawet jeśli tag jest pominięty.

    Zalecamy jednak, aby deweloperzy stron internetowych dodawali tag <meta name="color-scheme" content="dark light"> do swoich witryn, aby mieć pewność, że treści będą się prawidłowo wyświetlać w widokach WebView z konfiguracją domyślną.

  • DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: W przypadku „przyciemniania za pomocą agenta użytkownika” WebView ignoruje przyciemnianie strony internetowej i stosuje automatyczne przyciemnianie.

Jeśli aplikacja wyświetla treści internetowe własne, które zostały dostosowane za pomocą prefers-color-schemezapytania o multimedia, zalecamy DARK_STRATEGY_WEB_THEME_DARKENING_ONLYsprawdzenie, czy biblioteka WebView używa motywu niestandardowego.

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