Ajouter des aperçus générés à votre sélecteur de widgets

Les aperçus de widgets générés vous permettent de créer des aperçus dynamiques et personnalisés de vos widgets, qui reflètent précisément leur apparence sur l'écran d'accueil d'un utilisateur. Ils sont fournis via une API push, ce qui signifie que votre application fournit l'aperçu à tout moment de son cycle de vie sans recevoir de requête explicite de l'hôte du widget.

Ce guide explique comment fournir des aperçus pour les widgets basés sur Glance. Si votre widget est implémenté avec RemoteViews, consultez Ajouter des aperçus au sélecteur de widgets.

Pour améliorer l'expérience de sélection des widgets Glance de votre application, fournissez un aperçu du widget généré à l'aide de GlanceAppWidget.providePreview sur les appareils Android 15 ou version ultérieure, et spécifiez un previewImage pour les versions antérieures, et comme solution de secours sur Android 15 ou version ultérieure si aucun aperçu généré n'est disponible.

Pour en savoir plus, consultez Enrich your app with live updates and widgets (Enrichir votre application avec des infos en direct et des widgets) sur YouTube.

Configurer votre application pour les aperçus de widgets générés

Pour afficher les aperçus de widgets générés sur un appareil Android 15 ou version ultérieure, définissez d'abord la valeur compileSdk sur 35 ou plus dans le fichier build.gradle du module afin d'activer les aperçus générés dans le sélecteur de widgets.

Les applications peuvent ensuite utiliser setWidgetPreview dans GlanceAppWidgetManager. Pour éviter les utilisations abusives et limiter les problèmes d'état du système, setWidgetPreview est une API à débit limité. La limite par défaut est d'environ deux appels par heure.

Générer un aperçu mis à jour avec Jetpack Glance

Pour les widgets créés avec Jetpack Glance, procédez comme suit :

1. Remplacez la fonction GlanceAppWidget.providePreview pour fournir le contenu composable de l'aperçu. Comme vous le feriez dans provideGlance, chargez les données de votre application et transmettez-les au composable de contenu du widget pour que l'aperçu affiche des données précises. Contrairement à provideGlance, il s'agit d'une composition unique sans recomposition ni effets.

2. Appelez GlanceAppWidgetManager.setWidgetPreviews pour générer et publier l'aperçu.

Le système ne fournit pas de rappel pour les aperçus. Votre application doit donc décider quand appeler setWidgetPreviews. La stratégie de mise à jour dépend du cas d'utilisation de votre widget :

• Si le widget contient des informations statiques ou s'il s'agit d'une action rapide, définissez l'aperçu lors du premier lancement de l'application.
• Vous pouvez définir l'aperçu une fois que votre application dispose de données, par exemple après la connexion d'un utilisateur ou la configuration initiale.
• Vous pouvez configurer une tâche périodique pour mettre à jour les aperçus à la fréquence de votre choix.

Résoudre les problèmes liés aux aperçus générés

Un problème courant est qu'après avoir généré un aperçu, des images, des icônes ou d'autres composables peuvent être manquants dans l'image d'aperçu, par rapport à la taille de dépôt du widget. Cette taille de dépôt est définie par targetCellWidth et targetCellHeight, si spécifié, ou par minWidth et minHeight dans le fichier d'informations du fournisseur de widgets d'application.

En effet, par défaut, Android n'affiche que les composables visibles à la taille minimale du widget. En d'autres termes, Android définit par défaut previewSizeMode sur SizeMode.Single. Il utilise android:minHeight et android:minWidth dans le fichier XML d'informations du fournisseur de widget d'application pour déterminer les composables à dessiner.

Pour résoudre ce problème, remplacez previewSizeMode dans votre GlanceAppWidget et définissez-le sur SizeMode.Responsive, en fournissant un ensemble de valeurs DpSize. Cela indique à Android toutes les tailles de mise en page qu'il doit afficher pour l'aperçu, ce qui garantit que tous les éléments s'affichent correctement.

Optimisez l'application pour des facteurs de forme spécifiques. Indiquez une ou deux tailles à partir de la taille minimale et en suivant les points d'arrêt de votre widget. Spécifiez au moins un previewImage pour assurer la compatibilité avec les versions antérieures d'Android. Vous trouverez les valeurs de DP minimales appropriées pour différentes tailles de grille dans les consignes de conception des widgets.

Compatibilité avec les versions antérieures d'Android

Pour afficher les aperçus des widgets sur les appareils équipés d'Android 14 ou version antérieure, ou lorsqu'un aperçu généré n'est pas disponible sur Android 15 ou version ultérieure, spécifiez l'attribut previewImage.

Si vous modifiez l'apparence du widget, mettez à jour l'image d'aperçu.