Sous Android 10 ou version ultérieure, une application peut prendre en charge un thème sombre et passer automatiquement du thème clair au thème sombre en fonction du thème du système. Pour correspondre au thème actuel de l'application, le contenu Web de WebView peut également utiliser le style clair, sombre ou le style par défaut.
Le comportement de WebView interagit avec les normes Web prefers-color-scheme
et color-scheme
. Dans la mesure du possible, si vous créez le contenu Web que vous souhaitez que votre application affiche dans WebView, vous devez définir un thème sombre pour votre site Web et implémenter prefers-color-scheme
afin que WebView puisse faire correspondre le thème du contenu Web 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éfini sur true ou non. |
WebView affiche le contenu avec le thème clair défini par l'auteur du contenu. | WebView affiche le contenu avec le style par défaut défini par son auteur. |
L'application utilise Forcer le mode sombre pour appliquer algorithme un thème sombre à l'application. | WebView affiche le contenu avec le thème sombre défini par l'auteur du contenu. | Si l'auteur du contenu l'autorise, WebView affiche le contenu avec un thème sombre généré à l'aide d'un algorithme. |
L'application utilise un thème sombre avec isLightTheme défini sur false et n'autorise pas l'assombrissement algorithmique pour WebView. |
WebView affiche le contenu avec le thème sombre défini par l'auteur du contenu. | WebView affiche le contenu avec le style par défaut défini par son auteur. |
L'application utilise un thème sombre avec isLightTheme défini sur false et autorise l'assombrissement algorithmique pour WebView. |
WebView affiche le contenu avec le thème sombre défini par l'auteur du contenu. | Si l'auteur du contenu l'autorise, WebView affiche le contenu avec un thème sombre généré à l'aide d'un algorithme. |
Style de l'auteur du contenu
L'attribut isLightTheme
d'une application indique si son thème est clair ou sombre. WebView définit toujours prefers-color-scheme
selon isLightTheme
. Si isLightTheme
est true
ou n'est pas spécifié, prefers-color-scheme
est light
. Sinon, il s'agit de dark
.
Cela signifie que si le contenu Web utilise prefers-color-scheme
et que l'auteur du contenu le permet, le thème clair ou sombre défini par l'auteur du contenu est toujours appliqué automatiquement au contenu Web pour correspondre au thème de l'application.
Assombrissement algorithmique
Pour couvrir les cas où le contenu Web n'utilise pas prefers-color-scheme
, votre application peut autoriser WebView, si nécessaire, à appliquer de manière algorithmique un thème sombre au contenu Web qu'il affiche.
Si votre application utilise Forcer le mode sombre au niveau de l'application pour lui appliquer un thème sombre via un algorithme, consultez la section suivante qui explique comment autoriser l'assombrissement algorithmique du contenu Web avec le mode sombre de force.
Si votre application n'utilise pas le mode sombre de force, la façon dont elle spécifie quand autoriser l'assombrissement algorithmique dans WebView dépend du niveau d'API cible de votre application. Pour en savoir plus, consultez les sections suivantes pour les applications ciblant Android 13 ou version ultérieure et les applications ciblant Android 12 ou version antérieure.
Autoriser l'assombrissement algorithmique du contenu Web avec le mode sombre de force
Si votre application utilise la fonctionnalité Forcer le mode sombre au niveau de l'application, WebView applique un assombrissement algorithmique au contenu Web si les conditions suivantes sont remplies:
- La WebView et ses éléments parents autorisent le mode sombre.
- Le thème d'activité actuel 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 le paramètre
forceDarkMode
de WebView surFORCE_DARK_AUTO
et sa stratégie "Forcer le mode sombre" surDARK_STRATEGY_USER_AGENT_DARKENING_ONLY
.
WebView et tous ses parents peuvent autoriser le masquage forcé à l'aide de View.setForceDarkAllowed()
.
La valeur par défaut provient de l'attribut setForceDarkAllowed()
du thème Android, qui doit également être défini sur true
.
Le mode sombre forcé est principalement fourni pour assurer la rétrocompatibilité dans les applications qui ne fournissent pas leur propre thème sombre. Si votre application utilise le mode sombre, nous vous recommandons d'ajouter la prise en charge d'un thème sombre.
Autoriser l'assombrissement algorithmique (applis ciblant Android 13 ou version ultérieure)
Pour les applications qui n'utilisent pas le mode sombre au niveau de l'application et qui ciblent Android 13 (niveau d'API 33) ou version ultérieure, utilisez la méthode setAlgorithmicDarkeningAllowed()
d'AndroidX et transmettez true
pour spécifier qu'une WebView doit autoriser l'assombrissement algorithmique. Cette méthode est rétrocompatible avec les versions précédentes d'Android.
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 (applis ciblant Android 12 ou version antérieure)
Pour les applications qui n'utilisent pas le mode sombre au niveau de l'application et qui ciblent Android 12 (niveau d'API 32) ou version antérieure, utilisez FORCE_DARK_ON
pour autoriser l'assombrissement algorithmique.
Utilisez FORCE_DARK_ON
avec FORCE_DARK_OFF
si votre application fournit sa propre méthode pour basculer entre le thème clair et le thème sombre, par exemple un élément activable dans l'interface utilisateur ou une sélection temporelle automatique.
Pour vérifier si cette 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 des préférences système, elle doit écouter explicitement les modifications de thème et les appliquer à WebView avec les é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 l'API ForceDarkStrategy dans AndroidX pour contrôler l'assombrissement appliqué à une WebView donnée. Cette API n'est applicable que si l'option "Forcer le noir" est définie sur FORCE_DARK_ON
ou FORCE_DARK_AUTO
.
Avec l'API, votre application peut utiliser l'assombrissement du thème Web ou l'assombrissement user-agent:
- Assombrissement du thème Web: les développeurs Web peuvent appliquer
@media (prefers-color-scheme: dark)
pour contrôler l'apparence des pages Web en mode sombre. WebView affiche le contenu en fonction de ces paramètres. Pour en savoir plus sur l'assombrissement du thème Web, consultez la spécification. - Assombrissement du user-agent: WebView inverse automatiquement les couleurs de la page Web. Si vous utilisez l'assombrissement user-agent, la requête
@media (prefers-color-scheme: dark)
prend 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 options de stratégie acceptées sont les suivantes:
DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING
: il s'agit de l'option par défaut. Bien que la plupart des navigateurs considèrent la balise<meta name="color-scheme" content="dark light">
comme facultative, le mode par défaut d'Android WebView exige que la balise Meta respecte les requêtes médiaprefers-color-scheme
de la page Web. Vous pouvez utiliser des classes WebView en modeDARK_STRATEGY_WEB_THEME_DARKENING_ONLY
, auquel cas elles appliquent toujours les requêtes média, même si la balise est omise.Toutefois, nous recommandons aux développeurs Web d'ajouter la balise
<meta name="color-scheme" content="dark light">
à leurs sites Web pour s'assurer que le contenu s'affiche correctement dans les classes WebView avec la configuration par défaut.DARK_STRATEGY_USER_AGENT_DARKENING_ONLY
: appelé "assombrissement user-agent", WebView ignore l'assombrissement des pages Web et applique l'assombrissement automatique.
Si votre application affiche du contenu Web propriétaire que vous avez personnalisé avec la requête média prefers-color-scheme
, nous vous recommandons d'utiliser DARK_STRATEGY_WEB_THEME_DARKENING_ONLY
pour que WebView utilise le thème personnalisé.
Pour obtenir un exemple d'application du thème sombre, consultez la démonstration de WebView sur GitHub.