Améliorer votre widget

Cette page contient des informations sur les améliorations de widgets facultatives disponibles à partir d'Android 12 (niveau d'API 31). Ces fonctionnalités sont facultatives, mais elles sont simples à implémenter et à améliorer l'expérience de vos utilisateurs avec les 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 de fluidifier les transitions et de garantir la cohérence entre les différents widgets.

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

• Utilisez le thème par défaut du système (@android:style/Theme.DeviceDefault.DayNight) dans la mise en page racine.

• Utilisez le thème Material 3 (Theme.Material3.DynamicColors.DayNight) de la bibliothèque Material Components for Android, disponible à partir de la version 1.6.0 de Material Components for Android.

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 dans 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 "violet". La couleur d'accentuation et l'arrière-plan du widget s'adaptent aux modes clair et sombre, comme illustré dans 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>

Figure 1 Widget en thème clair.

Figure 2 : Widget avec le thème sombre.

Conseil :Nous vous recommandons d'utiliser le thème Material 3 pour suivre les consignes Material Design pour assurer la cohérence entre les appareils et la rétrocompatibilité.

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>

Remarque :Consultez la section Styles et thèmes pour un guide détaillé sur la gestion des différents styles, couleurs, attributs et thèmes.

Activer la compatibilité avec les commandes vocales

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 intents intégrés, 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 favorise l'engagement futur.

Par exemple, vous pouvez configurer le widget récapitulatif de l'entraînement de votre application d'exercice pour répondre aux commandes vocales de l'utilisateur 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 telles que "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'interactions utilisateur, ce qui permet à presque toutes les applications Android d'améliorer leurs widgets pour la voix. 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'améliorer l'expérience du sélecteur de widgets pour votre application en ajoutant des aperçus et des descriptions de widgets dynamiques.

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 la 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 entraînait parfois 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 par défaut ou de test 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 revenir à l'utilisation de 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>

Figure 3 Aperçu d'un widget qui s'affiche par défaut dans une zone de 3 x 3, mais qui peut tenir dans une zone de 3 x 1 en raison de 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 des valeurs par défaut en procédant comme suit:

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

  Remarque : Les valeurs définies à l'aide de la balise tools, comme tools:text="@string/my_wdiget_item_fake_1", ne s'affichent pas dans l'aperçu.

• Définir une image ou une icône par défaut ou d'espace réservé, telle que 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. L'un des avantages importants de cette approche est que vous pouvez fournir du contenu d'aperçu localisé.

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

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.

Ajouter 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 à afficher pour votre widget dans le sélecteur de widgets.

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

Fournissez une description de votre widget à l'aide de l'attribut description de l'élément <appwidget-provider> :

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

Remarque :Soyez concis. Il n'y a pas de limite de caractères, mais la représentation et l'espace disponible pour la description peuvent varier en fonction de l'appareil.

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

Créer des transitions plus fluides

À partir d'Android 12, les lanceurs offrent une transition plus fluide lorsqu'un utilisateur lance votre application à partir d'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>

Avertissement :Évitez d'utiliser des trampolines de diffusion. À partir d'Android 12, une application peut toujours lancer une activité à partir d'un broadcast receiver ou d'un service si elle est lancée à partir du PendingIntent d'un clic sur un widget. Toutefois, la nouvelle animation d'application n'est pas utilisée pour les applications lancées à partir d'un broadcast receiver ou d'un service, ce qui entraîne une mauvaise expérience utilisateur.

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

Utiliser la modification d'exécution de RemoteViews

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

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);