Assombrir le contenu Web dans WebView

Sous Android 10 ou version ultérieure, une application peut être compatible avec le 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 dans WebView peut également utiliser un style clair, sombre ou par défaut.

Le comportement de WebView interagit avec les prefers-color-scheme et color-scheme normes Web. Si 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 à celui 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 qui utilise 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 défini. 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 l' auteur du contenu.
L'application utilise Forcer un thème sombre pour appliquer un thème sombre de manière algorithmique à 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 l'application 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 l' auteur du contenu.
L'application utilise un thème sombre avec isLightTheme défini sur false et l'application 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 le thème de l'application est clair ou sombre. WebView définit toujours prefers-color-scheme en fonction de isLightTheme. Si isLightTheme est true ou n'est pas spécifié, prefers-color-scheme est light. Sinon, il est dark.

Cela signifie que si le contenu Web utilise prefers-color-scheme et que l'auteur du contenu l'autorise, le thème clair ou sombre défini par l'auteur du contenu est toujours automatiquement appliqué 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'elle affiche.

Si votre application utilise Forcer le mode sombre au niveau de l'application pour appliquer un thème sombre à votre application de manière algorithmique, consultez la section suivante qui décrit comment autoriser l'assombrissement algorithmique pour le contenu Web avec Forcer le mode sombre.

Si votre application n'utilise pas Forcer le mode sombre, 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 pour le contenu Web avec Forcer un thème sombre

Si votre application utilise Forcer un thème sombre au niveau de l'application , WebView applique l'assombrissement algorithmique au contenu Web si les conditions suivantes sont remplies :

  • WebView et ses éléments parents autorisent Forcer un thème sombre.
  • Le thème d'activité actuel est marqué comme clair avec isLightTheme défini sur true.
  • 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 sur FORCE_DARK_AUTO et sa stratégie Forcer un thème sombre sur DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

WebView et tous ses parents peuvent autoriser Forcer le mode sombre à l'aide de View.setForceDarkAllowed(). La valeur par défaut est extraite de l'attribut setForceDarkAllowed() du thème Android, qui doit également être défini sur true.

Forcer un thème sombre est principalement fourni pour la rétrocompatibilité dans les applications qui ne proposent pas leur propre thème sombre. Si votre application utilise Forcer un thème sombre, nous vous recommandons d'ajouter la compatibilité avec un thème sombre.

Autoriser l'assombrissement algorithmique (applications ciblant Android 13 ou version ultérieure)

Pour les applications qui n'utilisent pas Forcer un thème sombre au niveau de l'application et qui ciblent Android 13 (niveau d'API 33) ou version ultérieure, utilisez la méthode Jetpack Webkit setAlgorithmicDarkeningAllowed() et transmettez true pour spécifier qu'un WebView doit autoriser l'assombrissement algorithmique. Cette méthode est rétrocompatible avec les versions précédentes d'Android.

WebView applique ensuite l'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 applications qui n'utilisent pas Forcer un thème 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 les thèmes clair et sombre, par exemple un élément activable dans l'UI ou une sélection automatique basée sur l'heure.

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 changements 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 la bibliothèque Jetpack pour contrôler la façon dont l'assombrissement est appliqué à un WebView donné. Cette API ne s'applique que si Forcer le mode sombre est défini sur FORCE_DARK_ON ou FORCE_DARK_AUTO.

Grâce à l'API, votre application peut utiliser l'assombrissement du thème Web ou l'assombrissement de l'agent utilisateur :

  • 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 de l'agent utilisateur : WebView inverse automatiquement les couleurs de la page Web. Si vous utilisez l'assombrissement de l'agent utilisateur, la requête @media (prefers-color-scheme: dark) est évaluée sur false.

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 compatibles 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 traitent la <meta name="color-scheme" content="dark light"> balise comme facultative, le mode par défaut d'Android WebView's nécessite que la balise meta respecte les prefers-color-scheme requêtes média de la page Web. Vous pouvez utiliser des WebView avec DARK_STRATEGY_WEB_THEME_DARKENING_ONLY mode, auquel cas WebView applique toujours les requêtes média, même si la balise est omise.

    Toutefois, nous recommandons aux développeurs Web d'ajouter <meta name="color-scheme" content="dark light"> balise à leurs sites Web pour s'assurer que le contenu s'affiche correctement dans les WebView avec la configuration par défaut.

  • DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: appelé "assombrissement de l'agent utilisateur", WebView ignore tout assombrissement de la page Web et applique un 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 vous assurer que WebView utilise le thème personnalisé.

Pour obtenir un exemple de thème sombre appliqué, consultez la démo WebView sur GitHub