Przyciemnianie treści z internetu w komponencie WebView

W Androidzie 10 lub nowszym aplikacja może obsługiwać Ciemny motyw i zmieniane automatycznie między jasnym i ciemnym motywem aplikacji w zależności od motywu systemu. Aby dopasować bieżący motyw aplikacji, treści z internetu w komponencie WebView można też używać stylu jasnego, ciemnego lub domyślnego.

Działanie komponentu WebView współdziała z prefers-color-scheme oraz color-scheme i standardami internetowymi. jeśli tylko jest to możliwe, jeśli tworzysz treści internetowe, które chcesz aby Twoja aplikacja wyświetlała się w komponencie WebView, zdefiniuj ciemny motyw witrynie oraz zaimplementuj prefers-color-scheme, aby WebView mógł dopasowywać treść internetową do motywu aplikacji.

W tabeli poniżej opisujemy, jak WebView renderuje treści z internetu w Twojej aplikacji: w zależności od stylu treści internetowych i warunków aplikacji:

Warunki aplikacji Treści internetowe korzystające z pola prefers-color-scheme Treści internetowe, które nie korzystają z prefers-color-scheme
Aplikacja używa jasnego motywu z: isLightTheme ustawiono na true lub nie. WebView renderuje treści z jasnym motywem, określony przez autora treści. WebView renderuje treści zgodnie ze stylem domyślnym zdefiniowanym przez i autora treści.
Aplikacja używa Wymuś tryb ciemny do stosuj algorytm algorytmiczny ciemny motyw do aplikacji. WebView renderuje treści z ciemnym motywem, określony przez autora treści. Jeśli na to zezwolił autor treści, WebView renderuje treść za pomocą parametru ciemny motyw wygenerowany za pomocą algorytmu.
Aplikacja używa ciemnego motywu z isLightTheme ma wartość false, a aplikacja nie zezwala na korzystanie z algorytmów dla komponentu WebView. WebView renderuje treści z ciemnym motywem, określony przez autora treści. WebView renderuje treści zgodnie ze stylem domyślnym zdefiniowanym przez i autora treści.
Aplikacja używa ciemnego motywu z isLightTheme jest ustawione na false, a aplikacja zezwala algorytmiczne przyciemnianie w komponencie WebView. WebView renderuje treści z ciemnym motywem, określony przez autora treści. Jeśli na to zezwolił autor treści, WebView renderuje treść za pomocą parametru ciemny motyw wygenerowany za pomocą algorytmu.

Styl autora treści

Adres URL aplikacji Atrybut isLightTheme wskazuje, czy motyw aplikacji jest jasny czy ciemny. WebView zawsze ustawia prefers-color-scheme według: isLightTheme. Jeśli isLightTheme to true lub nie określono, to prefers-color-scheme to light; w przeciwnym razie jest dark.

Oznacza to, że jeśli treści internetowe zawierają właściwość prefers-color-scheme, a zawartość autor pozwala na to, jasny lub ciemny motyw zdefiniowany przez autora treści. jest zawsze automatycznie stosowany do treści z internetu, aby dopasować się do motywu aplikacji.

Algorytm ściemniania

Aby uwzględnić przypadki, w których treści z internetu nie zawierają tagu prefers-color-scheme aplikacja może w razie potrzeby zezwolić komponentowi WebView na algorytmiczne stosowanie ciemnego do renderowanych treści internetowych.

Jeśli Twoja aplikacja używa ustawienia na poziomie aplikacji Wymuś tryb ciemny na algorytm jak zastosować ciemny motyw w aplikacji, zapoznaj się z sekcją poniżej, zezwalaj na algorytmiczne przyciemnianie treści z internetu za pomocą opcji Wymuś tryb ciemny.

Jeśli aplikacja nie używa wymuszania trybu ciemnego, w jaki sposób aplikacja określa, kiedy zezwolić na tryb ciemny algorytmiczne ciemnienie w WebView zależy od docelowy poziom interfejsu API. W sekcjach poniżej znajdziesz informacje o aplikacjach kierowanych na Androida 13 lub nowszego oraz aplikacje kierowane na Androida 12 lub starszego.

Zezwalaj na przyciemnianie treści z internetu przez algorytm za pomocą funkcji Wymuś tryb ciemny

Jeśli Twoja aplikacja używa ustawienia na poziomie aplikacji Wymuś tryb ciemny, obowiązuje komponent WebView algorytmiczne przyciemnianie treści internetowych, jeśli są spełnione te warunki:

  • Komponent WebView i jego elementy nadrzędne umożliwiają włączenie trybu ciemnego.
  • Bieżący motyw aktywności jest oznaczony jako jasny z isLightTheme – ustawiono na true
  • Autor treści internetowych nie wyłącza wprost przyciemnienia.
  • W przypadku aplikacji kierowanych na Androida 13 (poziom interfejsu API 33) lub nowszego nie używa prefers-color-scheme.
  • W przypadku aplikacji kierowanych na Androida 12 (poziom interfejsu API 32) lub starszego: aplikacja ma Ustawienie forceDarkMode komponentu WebView do FORCE_DARK_AUTO i ustawili strategię Force Dark na DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

Komponent WebView i wszystkie jego elementy nadrzędne mogą zezwalać na wymuszanie trybu ciemnego przy użyciu View.setForceDarkAllowed() Wartość domyślna jest pobierana z atrybutu setForceDarkAllowed() parametru Motyw Androida, który też musi być ustawiony na true.

Wymuszanie trybu ciemnego jest stosowane głównie w celu zapewnienia zgodności wstecznej w aplikacjach, które nie udostępniają własnego ciemnego motywu. Jeśli aplikacja używa wymuszania trybu ciemnego, zalecamy obsługę ciemnego motywu.

Zezwalaj na przyciemnianie algorytmiczne (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 nowszej, należy używać AndroidaX. setAlgorithmicDarkeningAllowed() i przekazać w polu true, aby określić, że komponent WebView powinien zezwalać na przyciemnienie. Ta metoda jest zgodna wstecznie z poprzednimi wersjami Androida wersji.

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

  • Treści z internetu nie korzystają z tagu prefers-color-scheme.
  • Autor treści internetowych nie wyłącza wprost przyciemnienia.

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

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 niższej, użyj FORCE_DARK_ON aby umożliwić wykorzystanie algorytmicznego przyciemniania.

Używaj FORCE_DARK_ON w połączeniu z: FORCE_DARK_OFF. jeśli aplikacja udostępnia własną metodę przełączania między jasnym i ciemnym motywem, takich jak możliwość przełączania elementów w interfejsie lub automatyczny wybór na podstawie czasu.

Aby sprawdzić, czy funkcja jest obsługiwana, dodaj te wiersze kodu podczas konfigurowania obiektu WebView, np. w Activity.onCreate:

Kotlin

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

Java

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

Jeśli aplikacja wykrywa zmiany w ustawieniach systemu, nasłuchuj zmian motywu i zastosuj je do WebView za pomocą FORCE_DARK_ON i FORCE_DARK_OFF stanu.

Fragment kodu poniżej 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;
    }
}

Dostosuj obsługę ciemnego motywu

Możesz też użyć usługi Interfejs API ForceDarkStrategy w AndroidzieX. Ten interfejs API jest ma zastosowanie tylko wtedy, gdy wymuszanie trybu ciemnego jest ustawione na FORCE_DARK_ON lub FORCE_DARK_AUTO.

Aplikacja może używać interfejsu API, aby przyciemnić motyw strony internetowej lub zastosować klienta użytkownika przyciemnienie:

  • Przyciemnianie motywów internetowych: mogą obowiązywać deweloperzy stron internetowych. @media (prefers-color-scheme: dark), aby kontrolować wygląd stron internetowych w tryb ciemny. WebView renderuje treści zgodnie z tymi ustawieniami. Więcej informacji na temat: przyciemnianie motywu internetowego, zobacz specification.
  • Przyciemnienie klienta użytkownika: komponent WebView automatycznie odwraca kolory z internetu. stronę. Jeśli użyjesz przyciemnienia na potrzeby klienta użytkownika, Zapytanie @media (prefers-color-scheme: dark) zwraca wartość false.

Aby wybrać jedną z tych 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: Jest to opcja domyślna. Większość przeglądarek traktuje tag <meta name="color-scheme" content="dark light"> jako opcjonalny, Android Domyślny tryb WebView wymaga użycia tagu meta, który uwzględnia Zapytania o multimedia: prefers-color-scheme. Komponentów WebView możesz używać z: DARK_STRATEGY_WEB_THEME_DARKENING_ONLY w którym komponent WebView zawsze stosuje zapytania o media, nawet jeśli tag to pominięto.

    Zalecamy jednak dodanie <meta name="color-scheme" content="dark light"> tagu w swoich witrynach, upewnij się, że treść renderuje się prawidłowo w komponentach WebView z parametrem konfiguracji domyślnej.

  • DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: Nazywamy to „przyciemnieniem klienta użytkownika”. komponent WebView ignoruje przyciemnienie stron internetowych, stosuje automatyczne przyciemnianie.

Jeśli aplikacja wyświetla własne treści internetowe, które zostały dostosowane za pomocą tagu Zapytanie o media: prefers-color-scheme. Zalecamy DARK_STRATEGY_WEB_THEME_DARKENING_ONLY aby mieć pewność, że WebView będzie używać motywu niestandardowego.

Przykład zastosowanego ciemnego motywu znajdziesz Wersja demonstracyjna WebView w GitHubie