Améliorer votre widget

Essayer Compose
Jetpack Compose est le kit d'outils d'UI recommandé pour Android. Découvrez comment créer des widgets à l'aide d'API de style Compose.
Jetpack Glance →

Cette page fournit des informations sur les améliorations facultatives des widgets disponibles à partir d'Android 12 (niveau d'API 31). Ces fonctionnalités sont facultatives, mais elles sont faciles à implémenter et améliorent l'expérience utilisateur des widgets.

Utiliser des couleurs dynamiques

À partir d'Android 12, un widget peut utiliser les couleurs du thème de l'appareil pour les boutons, les arrière-plans et d'autres composants. Cela permet des transitions plus fluides et une cohérence entre les différents widgets.

Il existe deux façons d'obtenir des couleurs dynamiques :

Une fois le thème défini dans la mise en page racine, vous pouvez utiliser des attributs de couleur courants dans la racine ou l'un de ses enfants pour récupérer les couleurs dynamiques.

Voici quelques exemples d'attributs de couleur que vous pouvez utiliser :

  • ?attr/primary
  • ?attr/primaryContainer
  • ?attr/onPrimary
  • ?attr/onPrimaryContainer

Dans l'exemple suivant utilisant le thème Material 3, la couleur du thème de l'appareil est "violette". La couleur d'accentuation et l'arrière-plan du widget s'adaptent aux modes clair et sombre, comme illustré sur les figures 1 et 2.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="?attr/colorPrimaryContainer"
  android:theme="@style/Theme.Material3.DynamicColors.DayNight">

  <ImageView
    ...
    app:tint="?attr/colorPrimaryContainer"
    android:src="@drawable/ic_partly_cloudy" />

    <!-- Other widget content. -->

</LinearLayout>
Widget avec le thème clair
Figure 1. Widget avec le thème clair.
Widgets avec le thème Mode sombre
Figure 2 : Widget avec le thème sombre.

Rétrocompatibilité pour les couleurs dynamiques

Les couleurs dynamiques ne sont disponibles que sur les appareils équipés d'Android 12 ou version ultérieure. Pour fournir un thème personnalisé pour les versions antérieures, créez un thème par défaut avec vos couleurs personnalisées et un nouveau qualificatif (values-v31) à l'aide des attributs de thème par défaut.

Voici un exemple utilisant le thème Material 3 :

/values/styles.xml

<resources>
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
    <!-- Override default colorBackground attribute with custom color. -->
    <item name="android:colorBackground">@color/my_background_color</item>

    <!-- Add other colors/attributes. -->

  </style>
</resources>

/values-v31/styles.xml

<resources>
  <!-- Do not override any color attribute. -->
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>

/layout/my_widget_layout.xml

<resources>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:background="?android:attr/colorBackground"
    android:theme="@style/MyWidgetTheme" />
</resources>

Activer l'assistance vocale

Les actions dans les applications permettent à l'Assistant Google d'afficher des widgets en réponse aux commandes vocales pertinentes des utilisateurs. En configurant votre widget pour qu'il réponde aux intentions intégrées, votre application peut afficher de manière proactive des widgets sur les surfaces de l'Assistant telles qu'Android et Android Auto. Les utilisateurs ont la possibilité d'épingler les widgets affichés par l'Assistant à leur lanceur, ce qui encourage l'engagement futur.

Par exemple, vous pouvez configurer le widget de récapitulatif d'entraînement pour votre application d'exercice afin de répondre aux commandes vocales des utilisateurs qui déclenchent l'intent intégré GET_EXERCISE_OBSERVATION. L'Assistant affiche de manière proactive votre widget lorsque les utilisateurs déclenchent cet intent intégré en formulant des requêtes comme Hey Google, combien de kilomètres ai-je parcourus cette semaine sur ExempleApp ?

Il existe des dizaines d'intents intégrés couvrant plusieurs catégories d'interaction utilisateur, ce qui permet à presque toutes les applications Android d'améliorer leurs widgets pour la commande vocale. Pour commencer, consultez Intégrer les actions dans les applications avec les widgets Android.

Améliorer l'expérience du sélecteur de widgets de votre application

Android 12 vous permet d'ajouter des aperçus de widgets mis à l'échelle et des descriptions de widgets. Android 15 vous permet d'améliorer l'expérience du sélecteur de widgets pour votre application grâce à des aperçus de widgets générés.

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.

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

Les applications doivent définir la valeur compileSdk sur 35 ou version ultérieure dans le fichier build.gradle du module pour pouvoir fournir RemoteViews au sélecteur de widgets sur les appareils équipés d'Android 15 ou version ultérieure. Cela signifie que les applications peuvent mettre à jour le contenu du sélecteur pour qu'il soit plus représentatif de ce que voit l'utilisateur.

Les applications peuvent utiliser les méthodes AppWidgetManager, setWidgetPreview et getWidgetPreview pour mettre à jour l'apparence de leurs widgets avec des informations à jour et personnalisées.

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

Glance.compose exécute une composition. Par conséquent, aucune fonction de suspension, aucun flux ni aucun appel asynchrone similaire n'est utilisé dans le corps de votre composable. Vous devez plutôt utiliser des données constantes.

L'exemple suivant utilise Jetpack Glance pour générer un aperçu mis à jour. 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,
    ExampleAppWidget().compose(
        context = appContext
    ),
)

AppWidgetSnippets.kt

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)
)
AppWidgetSnippets.kt

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.

Approches recommandées pour créer des aperçus précis

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 :

<appwidget-provider
    ...
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
Image montrant un aperçu d&#39;un widget
Figure 3. Aperçu d'un widget qui apparaît par défaut dans une zone 3x3, mais qui peut tenir dans une zone 3x1 grâce à sa mise en page XML.

Pour afficher un aperçu précis, vous pouvez fournir directement la mise en page réelle du widget avec les valeurs par défaut en procédant comme suit :

  • Définition de android:text="@string/my_widget_item_fake_1" pour les éléments TextView.

  • Définir une image ou une icône par défaut ou de substitution, comme android:src="@drawable/my_widget_icon", pour les composants ImageView.

Sans valeurs par défaut, l'aperçu peut afficher des valeurs incorrectes ou vides. Un avantage important de cette approche est que vous pouvez fournir un contenu d'aperçu localisé.

Pour connaître les approches recommandées pour les aperçus plus complexes contenant ListView, GridView ou StackView, consultez Créer des aperçus précis incluant des éléments dynamiques pour en savoir plus.

Rétrocompatibilité avec les aperçus de widgets évolutifs

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, spécifiez l'attribut previewImage.

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

Donner un nom à votre widget

Les widgets doivent avoir un nom unique lorsqu'ils sont affichés dans le sélecteur de widgets.

Les noms des widgets sont chargés à partir de l'attribut label de l'élément receiver du widget dans le fichier AndroidManifest.xml.

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

Ajouter une description pour votre widget

À partir d'Android 12, fournissez une description du sélecteur de widgets à afficher pour votre widget.

Image montrant un sélecteur de widgets affichant un widget et sa description
Figure 4 : Exemple de sélecteur de widgets affichant un widget et sa description.

Fournissez une description de votre widget à l'aide de l'attribut description de l'élément &lt;appwidget-provider&gt; :

<appwidget-provider
    android:description="@string/my_widget_description">
</appwidget-provider>

Vous pouvez utiliser l'attribut descriptionRes sur les versions précédentes d'Android, mais il est ignoré par le sélecteur de widgets.

Activer des transitions plus fluides

À partir d'Android 12, les lanceurs d'applications offrent une transition plus fluide lorsqu'un utilisateur lance votre application depuis un widget.

Pour activer cette transition améliorée, utilisez @android:id/background ou android.R.id.background pour identifier votre élément d'arrière-plan :

// Top-level layout of the widget.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

Votre application peut utiliser @android:id/background sur les versions précédentes d'Android sans problème, mais il est ignoré.

Utiliser la modification de RemoteViews au moment de l'exécution

À partir d'Android 12, vous pouvez profiter de plusieurs méthodes RemoteViews qui permettent la modification au moment de l'exécution des attributs RemoteViews. Pour obtenir la liste complète des méthodes ajoutées, consultez la documentation de référence de l'API RemoteViews.

L'exemple de code suivant montre comment utiliser certaines de ces méthodes.

Kotlin

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList())

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)

Java

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList());

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);