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 précisément la façon dont ils apparaîtront 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.
Pour améliorer l'expérience du sélecteur de widgets de votre application, fournissez un aperçu de widget généré sur les appareils équipés d'Android 15 ou version ultérieure, un aperçu de widget mis à l'échelle (en spécifiant un previewLayout) pour les appareils équipés d'Android 12 à Android 14, et un previewImage pour les versions antérieures.
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 ou AppWidgetManager. Pour éviter toute utilisation abusive 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 vous assurer 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 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 à partir de la taille minimale et en suivant les points d'arrêt de votre widget. Spécifiez au moins une image pour assurer la rétrocompatibilité. Vous trouverez les valeurs DP minimales appropriées pour différentes tailles de grille dans les conseils de conception des widgets.
Générer un aperçu mis à jour sans Jetpack Glance
Vous pouvez utiliser RemoteViews sans Glance. L'exemple suivant charge une ressource de mise en page de widget XML et la définit comme aperçu. Un paramètre de compilation compileSdk de 35 ou version ultérieure est requis pour que setWidgetPreview s'affiche en tant que méthode dans cet extrait.
AppWidgetManager.getInstance(appContext).setWidgetPreview(
ComponentName(
appContext,
ExampleAppWidgetReceiver::class.java
),
AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
RemoteViews("com.example", R.layout.widget_preview)
)
Ajouter des aperçus de widgets évolutifs au sélecteur de widgets
À partir d'Android 12, l'aperçu du widget affiché dans le sélecteur de widgets est évolutif. Vous le fournissez sous forme de mise en page XML définie sur la taille par défaut du widget. Auparavant, l'aperçu du widget était une ressource drawable statique, ce qui, dans certains cas, entraînait des aperçus qui ne reflétaient pas précisément l'apparence des widgets lorsqu'ils étaient ajoutés à l'écran d'accueil.
Pour implémenter des aperçus de widgets évolutifs, utilisez l'attribut previewLayout de l'élément appwidget-provider pour fournir une mise en page XML à la place :
<appwidget-provider
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
Nous vous recommandons d'utiliser la même mise en page que le widget réel, avec des valeurs de test ou par défaut réalistes. La plupart des applications utilisent les mêmes previewLayout et initialLayout. Pour obtenir des conseils sur la création de mises en page d'aperçu précises, consultez la section suivante de cette page.
Nous vous recommandons de spécifier les attributs previewLayout et previewImage afin que votre application puisse utiliser previewImage si l'appareil de l'utilisateur n'est pas compatible avec previewLayout. L'attribut previewLayout est prioritaire sur l'attribut previewImage.
Rétrocompatibilité avec les aperçus de widgets
Pour permettre aux sélecteurs de widgets sur Android 11 (niveau d'API 30) ou version antérieure d'afficher des aperçus de votre widget, ou en tant que solution de secours pour les aperçus générés, spécifiez l'attribut previewImage.
Si vous modifiez l'apparence du widget, mettez à jour l'image d'aperçu.
Créer des aperçus précis incluant des éléments dynamiques
Cette section explique l'approche recommandée pour afficher plusieurs éléments dans un aperçu de widget pour un widget avec une vue de collection, c'est-à-dire un widget qui utilise un ListView, un GridView ou un StackView. Cela ne s'applique pas aux aperçus de widgets générés.
Si votre widget utilise l'une de ces vues, la création d'un aperçu évolutif en fournissant directement la mise en page du widget dégrade l'expérience lorsque l'aperçu du widget n'affiche aucun élément. Cela se produit parce que les données de la vue de collection sont définies de manière dynamique au moment de l'exécution, et cela ressemble à l'image illustrée à la figure 1.
Pour que les aperçus des widgets avec des vues de collection s'affichent correctement dans le sélecteur de widgets, nous vous recommandons de conserver un fichier de mise en page distinct désigné uniquement pour l'aperçu. Ce fichier de mise en page distinct doit inclure les éléments suivants :
- Mise en page réelle du widget.
- Vue de collection d'espace réservé avec des éléments fictifs. Par exemple, vous pouvez imiter un
ListViewen fournissant un espace réservéLinearLayoutavec plusieurs faux éléments de liste.
Pour illustrer un exemple de ListView, commencez par un fichier de mise en page distinct :
// res/layout/widget_preview.xml
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="@drawable/widget_background"
android:orientation="vertical">
// Include the actual widget layout that contains ListView.
<include
layout="@layout/widget_view"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
// The number of fake items you include depends on the values you provide
// for minHeight or targetCellHeight in the AppWidgetProviderInfo
// definition.
<TextView android:text="@string/fake_item1"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginVertical="?attr/appWidgetInternalPadding" />
<TextView android:text="@string/fake_item2"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginVertical="?attr/appWidgetInternalPadding" />
</LinearLayout>
Spécifiez le fichier de mise en page de l'aperçu lorsque vous fournissez l'attribut previewLayout des métadonnées AppWidgetProviderInfo. Vous devez toujours spécifier la mise en page réelle du widget pour l'attribut initialLayout et utiliser la mise en page réelle du widget lors de la construction d'un RemoteViews au moment de l'exécution.
<appwidget-provider
previewLayout="@layout/widget_previe"
initialLayout="@layout/widget_view" />
Éléments de liste complexes
L'exemple de la section précédente fournit de faux éléments de liste, car les éléments de liste sont des objets TextView. Il peut être plus complexe de fournir de faux éléments si les mises en page sont complexes.
Prenons l'exemple d'un élément de liste défini dans widget_list_item.xml et composé de deux objets TextView :
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="wrap_content">
<TextView android:id="@id/title"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:text="@string/fake_title" />
<TextView android:id="@id/content"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:text="@string/fake_content" />
</LinearLayout>
Pour fournir de faux éléments de liste, vous pouvez inclure la mise en page plusieurs fois, mais cela rend chaque élément de liste identique. Pour fournir des éléments de liste uniques, procédez comme suit :
Créez un ensemble d'attributs pour les valeurs de texte :
<resources> <attr name="widgetTitle" format="string" /> <attr name="widgetContent" format="string" /> </resources>Utilisez les attributs suivants pour définir le texte :
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="wrap_content"> <TextView android:id="@id/title" android:layout_width="match_parent" android:layout_height="wrap_content" android:text="?widgetTitle" /> <TextView android:id="@id/content" android:layout_width="match_parent" android:layout_height="wrap_content" android:text="?widgetContent" /> </LinearLayout>Créez autant de styles que nécessaire pour l'aperçu. Redéfinissez les valeurs de chaque style :
<resources> <style name="Theme.Widget.ListItem"> <item name="widgetTitle"></item> <item name="widgetContent"></item> </style> <style name="Theme.Widget.ListItem.Preview1"> <item name="widgetTitle">Fake Title 1</item> <item name="widgetContent">Fake content 1</item> </style> <style name="Theme.Widget.ListItem.Preview2"> <item name="widgetTitle">Fake title 2</item> <item name="widgetContent">Fake content 2</item> </style> </resources>Appliquez les styles aux faux éléments dans la mise en page de l'aperçu :
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="wrap_content" ...> <include layout="@layout/widget_view" ... /> <include layout="@layout/widget_list_item" android:theme="@style/Theme.Widget.ListItem.Preview1" /> <include layout="@layout/widget_list_item" android:theme="@style/Theme.Widget.ListItem.Preview2" /> </LinearLayout>