Créer un widget d'application avec Glance

manifeste, métadonnées

Les sections suivantes expliquent comment créer un widget d'application de base avec Glance.

Point clé : Glance offre une approche moderne pour créer des widgets d'application à l'aide de Compose, mais est limité par les contraintes de AppWidgets et RemoteViews. Par conséquent, Glance utilise des composables différents de l'UI Jetpack Compose.

Déclarer AppWidget dans le fichier manifeste

Après avoir effectué les étapes de configuration, déclarez AppWidget et ses métadonnées dans votre application.

1. Étendez le récepteur AppWidget à partir de GlanceAppWidgetReceiver :

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
       override val glanceAppWidget: GlanceAppWidget = TODO("Create GlanceAppWidget")
   }
   GlanceSnippets.kt

2. Enregistrez le fournisseur du widget d'application dans votre fichier AndroidManifest.xml et le fichier de métadonnées associé :

       <receiver android:name=".glance.MyReceiver"
       android:exported="true">
       <intent-filter>
           <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
       </intent-filter>
       <meta-data
           android:name="android.appwidget.provider"
           android:resource="@xml/my_app_widget_info" />
   </receiver>
   AndroidManifest.xml
   

Ajouter les métadonnées AppWidgetProviderInfo

Ensuite, suivez le guide Créer un widget pour créer et définir les informations du widget d'application dans le fichier @xml/my_app_widget_info.

La seule différence pour Glance est qu'il n'y a pas de fichier XML initialLayout, mais vous devez en définir un. Vous pouvez utiliser la mise en page de chargement prédéfinie fournie dans la bibliothèque :

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:initialLayout="@layout/glance_default_loading_layout">
</appwidget-provider>
my_app_widget_info.xml

Déclarer le fichier XML AppWidgetProviderInfo

L'objet AppWidgetProviderInfo définit les qualités essentielles de votre widget. Définissez AppWidgetProviderInfo dans votre fichier de ressources de métadonnées XML (res/xml/my_app_widget_info.xml) à l'intérieur d'un élément <appwidget-provider> :

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/glance_default_loading_layout"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

Attributs de dimensionnement des widgets

L'écran d'accueil par défaut positionne les widgets dans sa fenêtre en fonction d'une grille de cellules dont la hauteur et la largeur sont définies. La plupart des écrans d'accueil n'autorisent que les widgets dont la taille est un multiple entier des cellules de la grille (par exemple, deux cellules horizontalement sur trois cellules verticalement).

Les attributs de dimensionnement des widgets vous permettent de spécifier une taille par défaut pour votre widget et de fournir des limites inférieure et supérieure pour sa taille. Dans ce contexte, la taille par défaut d'un widget correspond à la taille qu'il prend lorsqu'il est ajouté à l'écran d'accueil pour la première fois.

Le tableau suivant décrit les attributs <appwidget-provider> liés à la taille du widget :

Attributs et description
targetCellWidth et targetCellHeight (Android 12), minWidth et minHeight	À partir d'Android 12, les attributs targetCellWidth et targetCellHeight spécifient la taille par défaut du widget en termes de cellules de grille. Ces attributs sont ignorés dans Android 11 et les versions antérieures, et peuvent être ignorés si l'écran d'accueil ne prend pas en charge une mise en page basée sur une grille. Les attributs minWidth et minHeight spécifient la taille par défaut du widget en dp. Si les valeurs de largeur ou de hauteur minimales d'un widget ne correspondent pas aux dimensions des cellules, elles sont arrondies à la taille de cellule la plus proche. Nous vous recommandons de spécifier les deux ensembles d'attributs (targetCellWidth et targetCellHeight, et minWidth et minHeight) afin que votre application puisse revenir à l'utilisation de minWidth et minHeight si l'appareil de l'utilisateur ne prend pas en charge targetCellWidth et targetCellHeight. Si les attributs targetCellWidth et targetCellHeight sont acceptés, ils sont prioritaires sur les attributs minWidth et minHeight.
minResizeWidth et minResizeHeight	Spécifiez la taille minimale absolue du widget. Ces valeurs spécifient la taille en dessous de laquelle le widget est illisible ou inutilisable. L'utilisation de ces attributs permet à l'utilisateur de redimensionner le widget à une taille inférieure à celle par défaut. L'attribut minResizeWidth est ignoré s'il est supérieur à minWidth ou si le redimensionnement horizontal n'est pas activé. Consultez resizeMode. De même, l'attribut minResizeHeight est ignoré s'il est supérieur à minHeight ou si le redimensionnement vertical n'est pas activé.
maxResizeWidth et maxResizeHeight	Spécifiez la taille maximale recommandée du widget. Si les valeurs ne sont pas un multiple des dimensions des cellules de la grille, elles sont arrondies à la taille de cellule la plus proche. L'attribut maxResizeWidth est ignoré s'il est inférieur à minWidth ou si le redimensionnement horizontal n'est pas activé. Consultez resizeMode. De même, l'attribut maxResizeHeight est ignoré s'il est inférieur à minHeight ou si le redimensionnement vertical n'est pas activé. Introduit dans Android 12.
resizeMode	Spécifie les règles selon lesquelles un widget peut être redimensionné. Vous pouvez utiliser cet attribut pour rendre les widgets de l'écran d'accueil redimensionnables horizontalement, verticalement ou sur les deux axes. Les utilisateurs appuient de manière prolongée sur un widget pour afficher ses poignées de redimensionnement, puis font glisser les poignées horizontales ou verticales pour modifier sa taille sur la grille de mise en page. Les valeurs de l'attribut resizeMode incluent horizontal, vertical et none. Pour déclarer un widget comme redimensionnable horizontalement et verticalement, utilisez horizontal|vertical.

Exemple

Pour illustrer l'impact des attributs du tableau précédent sur la taille du widget, prenons les spécifications suivantes :

• Une cellule de grille mesure 30 dp de large et 50 dp de haut.
• La spécification d'attribut suivante est fournie :

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

À partir d'Android 12 :

Utilisez les attributs targetCellWidth et targetCellHeight comme taille par défaut du widget.

La taille par défaut du widget est de 2x2. Le widget peut être redimensionné jusqu'à 2x1 ou jusqu'à 4x3.

Android 11 et versions antérieures

Utilisez les attributs minWidth et minHeight pour calculer la taille par défaut du widget.

La largeur par défaut est Math.ceil(80 / 30) = 3.

La hauteur par défaut est Math.ceil(80 / 50) = 2.

La taille par défaut du widget est de 3x2. Vous pouvez redimensionner le widget jusqu'à 2x1 ou en plein écran.

Remarque : Jetpack Glance gère les modifications de mise en page dans provideGlance en réponse à la mise à l'échelle dynamique des cellules si vous utilisez SizeMode.Responsive ou SizeMode.Exact. Pour tirer parti de ces modes, consultez le guide Créer une UI avec Glance.

Attributs de widget supplémentaires

Le tableau suivant décrit les attributs <appwidget-provider> liés à des qualités autres que la taille du widget.

Attributs et description
updatePeriodMillis	Définit la fréquence à laquelle le framework de widget demande une mise à jour à partir de GlanceAppWidgetReceiver en appelant la méthode de rappel onUpdate(). Pour économiser la batterie, nous vous recommandons de mettre à jour la position aussi rarement que possible (pas plus d'une fois par heure). Pour en savoir plus, consultez la section Quand mettre à jour les widgets dans la gestion de l'état Glance.
initialLayout	Pointe vers la ressource de mise en page qui définit la mise en page de chargement du widget avant le rendu des compositions de l'UI Glance. Vous pouvez utiliser la mise en page de chargement prédéfinie fournie dans la bibliothèque : @layout/glance_default_loading_layout.
configure	Définit l'activité de configuration qui se lance lorsque l'utilisateur ajoute le widget. Consultez la section Implémenter une activité de configuration de widget sur cette page.
description	Indique la description à afficher pour votre widget dans le sélecteur de widgets. Introduit dans Android 12.
previewLayout (Android 12) et previewImage (Android 11 et versions antérieures)	À partir d'Android 12, l'attribut previewLayout spécifie un aperçu évolutif que vous fournissez sous la forme d'une mise en page XML définie sur la taille par défaut du widget. Dans l'idéal, il s'agit d'un mappage XML statique correspondant à la mise en page de votre conception. Dans Android 11 ou version antérieure, l'attribut previewImage spécifie une capture d'écran statique de l'apparence du widget, qui s'affiche dans le sélecteur de widgets. Nous vous recommandons de spécifier les deux afin que votre application puisse revenir à une version antérieure de manière fluide. Pour les plates-formes plus récentes (Android 15 et versions ultérieures), vous pouvez définir des aperçus générés en direct dans Kotlin à l'aide de `GlanceAppWidget.providePreview`. Consultez le guide des aperçus générés.
autoAdvanceViewId	Spécifie l'ID de vue de la sous-vue du widget qui est automatiquement avancée par l'hôte du widget.
widgetCategory	Déclare si votre widget peut être affiché sur l'écran d'accueil (home_screen), l'écran de verrouillage (keyguard) ou les deux. Pour Android 5.0 et les versions ultérieures, seule home_screen est valide.
widgetFeatures	Déclare les fonctionnalités prises en charge par le widget. Par exemple, si la configuration de votre widget est facultative, spécifiez à la fois configuration_optional et reconfigurable.

Définir GlanceAppWidget

1. Créez une classe qui étend GlanceAppWidget et remplace la méthode provideGlance. Il s'agit de la méthode qui vous permet de charger les données nécessaires pour afficher votre widget :

   Remarque : provideGlance s'exécute sur le thread principal. Pour effectuer des opérations de longue durée dans provideGlance, passez à un autre thread à l'aide de withContext. Pour en savoir plus sur l'exécution en dehors du thread principal, consultez Utiliser des coroutines pour la sécurité principale.

   class MyAppWidget : GlanceAppWidget() {
   
       override suspend fun provideGlance(context: Context, id: GlanceId) {
   
           // In this method, load data needed to render the AppWidget.
           // Use `withContext` to switch to another thread for long running
           // operations.
   
           provideContent {
               // create your AppWidget here
               Text("Hello World")
           }
       }
   }
   GlanceSnippets.kt

2. Instanciez-le dans le glanceAppWidget sur votre GlanceAppWidgetReceiver :

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
   
       // Let MyAppWidgetReceiver know which GlanceAppWidget to use
       override val glanceAppWidget: GlanceAppWidget = MyAppWidget()
   }
   GlanceSnippets.kt

Vous avez configuré un AppWidget à l'aide de Glance.

Utiliser la classe AppWidgetProvider pour gérer les diffusions de widgets

Le widget de coordonnées GlanceAppWidgetReceiver diffuse les mises à jour de l'état de la plate-forme en étendant le AppWidgetProvider sous-jacent. Il reçoit des événements de plate-forme lorsque votre widget est mis à jour, supprimé, activé ou désactivé, et les traduit en requêtes de cycle de vie Compose.

Déclarer un widget dans le fichier manifeste

Déclarez la sous-classe de votre classe GlanceAppWidgetReceiver comme broadcast receiver dans votre fichier AndroidManifest.xml :

<receiver android:name="ExampleAppWidgetReceiver"
          android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/my_app_widget_info" />
</receiver>

L'élément <receiver> nécessite l'attribut android:name, qui spécifie la classe du récepteur. Le récepteur doit accepter l'action de diffusion ACTION_APPWIDGET_UPDATE dans <intent-filter>.

L'élément <meta-data> doit identifier son nom comme android.appwidget.provider, et l'attribut android:resource doit pointer vers votre ressource de métadonnées XML AppWidgetProviderInfo (@xml/my_app_widget_info).

Implémenter la classe AppWidgetProvider

Dans Glance, vous étendez GlanceAppWidgetReceiver au lieu de AppWidgetProvider directement. Implémentez-le en associant votre récepteur à votre instance GlanceAppWidget. Les principaux rappels disponibles dans GlanceAppWidgetReceiver fonctionnent comme suit :

• onUpdate() : remplacé automatiquement par Glance pour exécuter les mises à jour de la composition. Si vous remplacez manuellement onUpdate, vous devez appeler super.onUpdate pour permettre à Glance de lancer correctement les threads de composition.
• onAppWidgetOptionsChanged() : appelée lorsque le widget est placé ou redimensionné pour la première fois. Les options de lecture rapide regroupent les éléments en coulisses afin que votre mise en page s'ajuste de manière fluide en fonction des dimensions d'exécution.
• onDeleted(Context, IntArray) : appelée chaque fois qu'une instance de widget spécifique est supprimée par l'utilisateur.
• onEnabled(Context) : déclenché lorsque la première instance de votre widget est créée. Excellent pour exécuter des migrations mondiales.
• onDisabled(Context) : appelé lorsque la dernière instance active du fournisseur est supprimée.
• onReceive(Context, Intent) : intercepte chaque diffusion de plate-forme avant des méthodes de rappel spécifiques. Vous devez vous assurer que toute logique de récepteur personnalisée que vous écrivez appelle super.onReceive(context, intent) et ne doit jamais appeler goAsync vous-même, car Glance achemine automatiquement le travail de manière asynchrone.

Avertissement : Étant donné que les récepteurs sont soumis à des limites strictes de 10 secondes en arrière-plan, les actions de longue durée ne doivent jamais s'exécuter dans les rappels de récepteur. Si vous devez effectuer des requêtes de base de données ou des recherches réseau complexes, déléguez la tâche à WorkManager et exécutez GlanceAppWidget().update() une fois la tâche terminée.

Recevoir les intents de diffusion des widgets

En coulisses, GlanceAppWidgetReceiver filtre et gère les intents de diffusion des widgets de plate-forme de base suivants :

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

Créer l'UI

L'extrait suivant montre comment créer l'UI :

/* Import Glance Composables
 In the event there is a name clash with the Compose classes of the same name,
 you may rename the imports per https://kotlinlang.org/docs/packages.html#imports
 using the `as` keyword.

import androidx.glance.Button
import androidx.glance.layout.Column
import androidx.glance.layout.Row
import androidx.glance.text.Text
*/
class MyAppWidget : GlanceAppWidget() {

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        // Load data needed to render the AppWidget.
        // Use `withContext` to switch to another thread for long running
        // operations.

        provideContent {
            // create your AppWidget here
            MyContent()
        }
    }

    @Composable
    private fun MyContent() {
        Column(
            modifier = GlanceModifier.fillMaxSize(),
            verticalAlignment = Alignment.Top,
            horizontalAlignment = Alignment.CenterHorizontally
        ) {
            Text(text = "Where to?", modifier = GlanceModifier.padding(12.dp))
            Row(horizontalAlignment = Alignment.CenterHorizontally) {
                Button(
                    text = "Home",
                    onClick = actionStartActivity<MyActivity>()
                )
                Button(
                    text = "Work",
                    onClick = actionStartActivity<MyActivity>()
                )
            }
        }
    }
}
GlanceSnippets.kt

L'exemple de code précédent effectue les opérations suivantes :

• Dans le Column de premier niveau, les éléments sont placés les uns après les autres, verticalement.
• Le Column étend sa taille pour correspondre à l'espace disponible (via GlanceModifier), aligne son contenu en haut (verticalAlignment) et le centre horizontalement (horizontalAlignment).
• Le contenu de Column est défini à l'aide du lambda. L'ordre est important.
  • Le premier élément de Column est un composant Text avec 12.dp de marge intérieure.
  • Le deuxième élément est un Row, où les éléments sont placés horizontalement les uns après les autres, avec deux Buttons centrés horizontalement (horizontalAlignment). L'affichage final dépend de l'espace disponible. Voici un exemple de ce à quoi cela peut ressembler :

Figure 1. Exemple d'UI.

Vous pouvez modifier les valeurs d'alignement ou appliquer différentes valeurs de modificateur (telles que la marge intérieure) pour modifier l'emplacement et la taille des composants. Consultez la documentation de référence pour obtenir la liste complète des composants, des paramètres et des modificateurs disponibles pour chaque classe.

Implémenter des angles arrondis

Android 12 introduit des paramètres système permettant de personnaliser dynamiquement le rayon des angles de vos widgets d'application :

• system_app_widget_background_radius : Spécifie le rayon d'angle du conteneur d'arrière-plan du widget (jamais supérieur à 28 dp).
• Rayon intérieur : pour éviter que le contenu ne soit coupé, calculez un rayon proportionnel pour votre contenu intérieur en fonction du contour de l'arrière-plan du système : systemRadiusValue - widgetPadding

Dans Glance, vous pouvez appliquer des propriétés de dimensionnement du rayon d'angle de manière dynamique dans la composition à l'aide de GlanceModifier.cornerRadius(android.R.dimen.system_app_widget_background_radius).

Pour assurer la rétrocompatibilité sur les appareils équipés d'Android 11 (niveau d'API 30) ou d'une version antérieure, implémentez des attributs personnalisés et des solutions de secours pour les ressources de thème personnalisées :

• /values/attrs.xml

  <resources>
  <attr name="backgroundRadius" format="dimension" />
  </resources>
  

• /values/styles.xml

  <resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
  </resources>
  

• /values-31/styles.xml

  <resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
  </resources>
  

• /drawable/my_widget_background.xml

  <shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  </shape>