Les aperçus de widgets générés vous permettent de créer des aperçus dynamiques et personnalisés pour vos widgets, qui reflètent fidèlement leur apparence sur l'écran d'accueil d'un utilisateur. Elles sont fournies via une API push, ce qui signifie que votre application fournit l'aperçu à tout moment de son cycle de vie sans recevoir de demande 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 dans votre application, fournissez un aperçu de widget généré à l'aide de GlanceAppWidget.providePreview sur les appareils Android 15 et versions ultérieures, et spécifiez un previewImage pour les versions antérieures, ainsi qu'en tant que solution de secours sur Android 15 et versions ultérieures si un aperçu généré n'est pas disponible.
Pour en savoir plus, consultez Enrichir votre application avec des mises à jour 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 des widgets générés sur un appareil équipé d'Android 15 ou version ultérieure, définissez d'abord la valeur compileSdk sur 35 ou une version ultérieure dans le fichier build.gradle du module pour pouvoir fournir RemoteViews au sélecteur de widgets.
Les applications peuvent ensuite utiliser setWidgetPreview dans GlanceAppWidgetManager. Pour éviter les utilisations abusives et atténuer les problèmes liés à l'é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 :
Remplacez la fonction
GlanceAppWidget.providePreviewpour fournir le contenu composable de l'aperçu. Comme vous le feriez dansprovideGlance, 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.Appelez
GlanceAppWidgetManager.setWidgetPreviewspour 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 que, après avoir généré un aperçu, des images, des icônes ou d'autres composables peuvent manquer 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, le cas échéant, ou par minWidth et minHeight dans le fichier d'informations du fournisseur de widgets d'application.
Cela se produit, car Android n'affiche par défaut que les composables visibles à la taille minimale du widget. En d'autres termes, Android définit previewSizeMode sur SizeMode.Single par défaut. 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 fichier 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 dont il a besoin pour le rendu de l'aperçu, ce qui garantit que tous les éléments s'affichent correctement.
Optimisez votre application pour des facteurs de forme spécifiques. Fournissez une ou deux tailles en commençant par la taille minimale et en suivant les points d'arrêt de votre widget. Spécifiez au moins un previewImage pour la rétrocompatibilité. Vous trouverez les valeurs DP minimales appropriées pour différentes tailles de grille dans les conseils de conception des widgets.
Rétrocompatibilité avec les aperçus de widgets
Pour permettre aux sélecteurs de widgets sur les appareils exécutant des versions antérieures à Android 15 d'afficher des aperçus de votre widget, ou en tant que solution de secours pour les aperçus générés sur Android 15 et versions ultérieures, spécifiez l'attribut previewImage.
Si vous modifiez l'apparence du widget, mettez à jour l'image d'aperçu.