Sous Android 10 ou version ultérieure, une application peut prendre en charge Thème sombre et changement automatique entre les thèmes d'application clair et sombre en fonction du thème du système. Pour faire correspondre les thème d'application actuel, contenu Web dans WebView vous pouvez également utiliser le style clair, sombre ou par défaut.
Le comportement de WebView interagit avec
prefers-color-scheme
et
color-scheme
les normes du Web. Lorsque cela est possible, si vous êtes l'auteur du contenu Web que vous souhaitez
votre application pour qu'elle s'affiche dans WebView, vous devez définir un thème sombre pour votre
site Web et
implémenter prefers-color-scheme
pour que WebView puisse correspondre à l'attribut
au thème de votre application.
Le tableau suivant décrit comment WebView affiche le contenu Web dans votre application, en fonction du style du contenu Web et des conditions de votre application:
Conditions de l'application | Contenu Web utilisant prefers-color-scheme |
Contenu Web qui n'utilise pas prefers-color-scheme |
---|---|---|
L'application utilise un thème clair avec
isLightTheme
définie sur true ou non définie. |
WebView affiche le contenu avec le thème clair qui défini par l'auteur du contenu. | WebView affiche le contenu avec le style par défaut défini par l'auteur du contenu. |
L'appli utilise actuellement Forcer le mode sombre à appliquer un thème sombre à l'aide d'algorithmes à l'application. | WebView affiche le contenu avec le thème sombre qui défini par l'auteur du contenu. | Si l'auteur du contenu l'y autorise, WebView affiche le contenu avec un un thème sombre généré à l'aide d'un algorithme. |
L'appli utilise un thème sombre avec
isLightTheme
définie sur false et l'application n'autorise pas les algorithmes
pour WebView. |
WebView affiche le contenu avec le thème sombre qui défini par l'auteur du contenu. | WebView affiche le contenu avec le style par défaut défini par l'auteur du contenu. |
L'appli utilise un thème sombre avec
isLightTheme
défini sur false alors que l'application autorise
assombrissement algorithme pour WebView. |
WebView affiche le contenu avec le thème sombre qui défini par l'auteur du contenu. | Si l'auteur du contenu l'y autorise, WebView affiche le contenu avec un un thème sombre généré à l'aide d'un algorithme. |
Style de l'auteur du contenu
Une application
Attribut isLightTheme
indique si le thème de l'application est clair ou sombre. WebView est toujours défini
prefers-color-scheme
selon isLightTheme
. Si isLightTheme
est true
ou non spécifié, prefers-color-scheme
est light
. sinon il s'agit
dark
Cela signifie que si le contenu Web utilise prefers-color-scheme
et que le contenu
l'auteur le permet, le thème clair ou sombre défini par l'auteur du contenu
est toujours appliquée automatiquement au contenu Web pour correspondre au thème de l'application.
Assombrissement algorithmique
Couvrir les cas où le contenu Web n'utilise pas
prefers-color-scheme
,
votre application peut autoriser WebView, si nécessaire, à appliquer un attribut sombre à l'aide d'algorithmes
au contenu Web qu'il affiche.
Si votre application utilise l'API Forcer le mode sombre à utiliser des algorithmes appliquer un thème sombre à votre application, consultez la section suivante pour savoir comment autoriser l'assombrissement algorithmique des contenus Web avec Force Dark.
Si votre application n'utilise pas le mode sombre forcée, comment votre application spécifie quand l'autoriser l'assombrissement algorithmique dans WebView dépend de l'état niveau d'API cible. Consultez les sections suivantes pour les applications ciblant Android 13 ou version ultérieure et applis ciblant Android 12 ou version antérieure.
Autoriser l'assombrissement algorithmique pour le contenu Web avec Force Dark
Si votre application utilise l'API Forcer le mode sombre, WebView s'applique un assombrissement algorithmique du contenu Web si les conditions suivantes sont remplies:
- La WebView et ses éléments parents autorisent l'option "Forcer le mode sombre".
- Le thème actuel de l'activité est marqué comme clair avec
isLightTheme
défini surtrue
- L'auteur du contenu Web ne désactive pas explicitement l'assombrissement.
- Pour les applications ciblant Android 13 (niveau d'API 33) ou version ultérieure, le contenu Web
n'utilise pas
prefers-color-scheme
. - Pour les applications ciblant Android 12 (niveau d'API 32) ou version antérieure: l'application a défini
Paramètre
forceDarkMode
de WebView àFORCE_DARK_AUTO
et a défini sa stratégie Force Dark surDARK_STRATEGY_USER_AGENT_DARKENING_ONLY
WebView et tous ses parents peuvent autoriser l'assombrissement forcé à l'aide de
View.setForceDarkAllowed()
La valeur par défaut provient de l'attribut setForceDarkAllowed()
de
Thème Android, qui doit également être défini sur true
.
Forcer le mode sombre est principalement fourni pour assurer la rétrocompatibilité dans les applications qui ne proposent pas leur propre thème sombre. Si votre application utilise le mode sombre, nous vous recommandons Prise en charge d'un thème sombre.
Autoriser l'assombrissement algorithmique (applis ciblant Android 13 ou version ultérieure)
Pour les applis qui n'utilisent pas le mode sombre au niveau de l'application et ciblent Android 13 (niveau d'API)
33) ou version ultérieure, utilisez AndroidX
setAlgorithmicDarkeningAllowed()
et transmettre true
pour indiquer qu'une WebView doit autoriser les algorithmes
s'assombrir. Cette méthode est rétrocompatible avec les versions précédentes d'Android
versions.
WebView applique ensuite un assombrissement algorithmique si les conditions suivantes sont remplies:
- Le contenu Web n'utilise pas
prefers-color-scheme
. - L'auteur du contenu Web ne désactive pas explicitement l'assombrissement.
Autoriser l'assombrissement algorithmique (applications ciblant Android 12 ou version antérieure)
Pour les applis qui n'utilisent pas le mode sombre au niveau de l'application et ciblent Android 12 (niveau d'API)
32) ou moins, utilisez
FORCE_DARK_ON
pour permettre l'assombrissement algorithmique.
Utiliser FORCE_DARK_ON
avec
FORCE_DARK_OFF
si votre application fournit sa propre méthode pour basculer entre les thèmes clair et sombre,
comme un élément activable dans l'UI ou une sélection automatique basée sur le temps.
Pour vérifier si la fonctionnalité est compatible, ajoutez les lignes de code suivantes
partout où vous configurez votre objet WebView, par exemple dans Activity.onCreate
:
Kotlin
if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) { WebSettingsCompat.setForceDark(...) }
Java
if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) { WebSettingsCompat.setForceDark(...); }
Si votre application repose sur la détection des modifications apportées aux préférences système, elle doit
écouter explicitement les modifications de thème et les appliquer à WebView avec
États FORCE_DARK_ON
et FORCE_DARK_OFF
.
L'extrait de code suivant montre comment modifier le format du thème:
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; } }
Personnaliser la gestion du thème sombre
Vous pouvez également utiliser
API ForceDarkStrategy
dans AndroidX pour contrôler la façon dont l'assombrissement est appliqué à une WebView donnée. Cette API est
applicable uniquement si l'option "Forcer l'assombrissement" est définie sur FORCE_DARK_ON
ou FORCE_DARK_AUTO
.
À l'aide de l'API, votre application peut utiliser l'assombrissement du thème Web ou le user-agent. assombrissement:
- Assombrissement du thème Web: les développeurs Web peuvent appliquer
@media (prefers-color-scheme: dark)
pour contrôler l'apparence des pages Web dans mode sombre. WebView affiche le contenu en fonction de ces paramètres. Pour en savoir plus sur l'assombrissement du thème Web, . - Assombrissement du user-agent: WebView inverse automatiquement les couleurs du Web.
. Si vous utilisez l'assombrissement user-agent,
La requête
@media (prefers-color-scheme: dark)
a la valeurfalse
.
Pour choisir entre les deux stratégies, utilisez l'API suivante:
Kotlin
if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK_STRATEGY)) { WebSettingsCompat.setForceDarkStrategy(...) }
Java
if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK_STRATEGY)) { WebSettingsCompat.setForceDarkStrategy(...); }
Les stratégies d'enchères acceptées sont les suivantes:
<ph type="x-smartling-placeholder"></ph>
DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING
: Il s'agit de l'option par défaut. Même si la plupart des navigateurs traitent le Balise<meta name="color-scheme" content="dark light">
facultative, Android Le mode par défaut de WebView nécessite que la balise Meta respecte les paramètresprefers-color-scheme
requêtes média. Vous pouvez utiliser des WebViews avec <ph type="x-smartling-placeholder"></ph>DARK_STRATEGY_WEB_THEME_DARKENING_ONLY
, auquel cas WebView applique toujours les requêtes média, même si le tag est sont omises.Toutefois, nous recommandons aux développeurs Web d'ajouter
<meta name="color-scheme" content="dark light">
sur son site Web pour vous assurer que le contenu s'affiche correctement dans les WebViews avec la propriété configuration par défaut.<ph type="x-smartling-placeholder"></ph>
DARK_STRATEGY_USER_AGENT_DARKENING_ONLY
: Appelée « user-agent assombrissement », la WebView ignore les éventuels assombrissements et applique un assombrissement automatique.
Si votre application affiche du contenu Web propriétaire que vous avez personnalisé avec le
prefers-color-scheme
requête média (nous vous recommandons)
DARK_STRATEGY_WEB_THEME_DARKENING_ONLY
pour vous assurer que WebView utilise le thème personnalisé.
Pour voir un exemple de thème sombre appliqué, consultez les Démonstration de WebView sur GitHub