Créer un hôte de widget

L'écran d'accueil Android, disponible sur la plupart des appareils Android, permet à l'utilisateur d'intégrer des widgets d'application (ou widgets) pour accéder rapidement au contenu. Si vous créez un écran d'accueil de remplacement ou une application similaire, vous pouvez également autoriser l'utilisateur à intégrer des widgets en implémentant AppWidgetHost. La plupart des applications n'ont pas besoin de suivre cette procédure, mais si vous créez votre propre hôte, il est important de comprendre les obligations contractuelles qu'un hôte accepte implicitement.

Cette page porte sur les responsabilités liées à l'implémentation d'un AppWidgetHost personnalisé. Pour obtenir un exemple spécifique d'implémentation d'un AppWidgetHost, consultez le code source de l'écran d'accueil Android LauncherAppWidgetHost.

Voici un aperçu des classes clés et des concepts impliqués dans l'implémentation d'un AppWidgetHost personnalisé:

• Hôte du widget d'application: AppWidgetHost fournit l'interaction avec le service AppWidget pour les applications qui intègrent des widgets dans leur interface utilisateur. Un AppWidgetHost doit avoir un ID unique dans le package de l'hôte. Cet ID persiste quelle que soit l'utilisation de l'hôte. L'ID est généralement une valeur codée en dur que vous attribuez dans votre application.

• App widget ID (ID du widget d'application) : chaque instance de widget reçoit un ID unique au moment de la liaison. Consultez bindAppWidgetIdIfAllowed() et, pour plus de détails, la section Liaison de widgets ci-dessous. L'hôte obtient l'identifiant unique à l'aide de allocateAppWidgetId(). Cet ID persiste pendant toute la durée de vie du widget jusqu'à ce qu'il soit supprimé de l'hôte. Tout état spécifique à l'hôte, tel que la taille et l'emplacement du widget, doit être conservé par le package d'hébergement et associé à l'ID du widget de l'application.

• Vue hôte du widget d'application: considérez AppWidgetHostView comme un cadre dans lequel le widget est encapsulé chaque fois qu'il doit être affiché. Un widget est associé à un AppWidgetHostView chaque fois qu'il est gonflé par l'hôte.

  • Par défaut, le système crée une AppWidgetHostView, mais l'hôte peut créer sa propre sous-classe de AppWidgetHostView en l'étendant.
  • À partir d'Android 12 (niveau d'API 31), AppWidgetHostView introduit les méthodes setColorResources() et resetColorResources() pour gérer les couleurs surchargées de manière dynamique. L'hôte est chargé de fournir les couleurs à ces méthodes.

• Groupe d'options: AppWidgetHost utilise le groupe d'options pour communiquer au AppWidgetProvider des informations sur l'affichage du widget (par exemple, la liste des plages de tailles) et pour indiquer si le widget se trouve sur un écran de verrouillage ou sur l'écran d'accueil. Ces informations permettent à AppWidgetProvider d'adapter le contenu et l'apparence du widget en fonction de l'emplacement et du mode d'affichage. Vous pouvez utiliser updateAppWidgetOptions() et updateAppWidgetSize() pour modifier le bundle d'un widget. Ces deux méthodes déclenchent le rappel onAppWidgetOptionsChanged() de AppWidgetProvider.

Lier des widgets

Lorsqu'un utilisateur ajoute un widget à un hôte, un processus appelé binding se produit. La liaison consiste à associer un ID de widget d'application particulier à un hôte spécifique et à un AppWidgetProvider spécifique.

Les API de liaison permettent également à un hôte de fournir une UI personnalisée pour la liaison. Pour utiliser ce processus, votre application doit déclarer l'autorisation BIND_APPWIDGET dans le fichier manifeste de l'hôte:

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

Mais ce n'est que la première étape. Au moment de l'exécution, l'utilisateur doit explicitement accorder l'autorisation à votre application pour lui permettre d'ajouter un widget à l'hôte. Pour vérifier si votre application est autorisée à ajouter le widget, utilisez la méthode bindAppWidgetIdIfAllowed(). Si bindAppWidgetIdIfAllowed() renvoie false, votre application doit afficher une boîte de dialogue invitant l'utilisateur à accorder l'autorisation: "autoriser" pour l'ajout actuel du widget ou "toujours autoriser" pour couvrir tous les futurs ajouts de widgets.

Cet extrait donne un exemple d'affichage de la boîte de dialogue:

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle described in the preceding section.
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

L'hôte doit vérifier si le widget ajouté par un utilisateur doit être configuré. Pour en savoir plus, consultez Autoriser les utilisateurs à configurer des widgets d'application.

Responsabilités de l'organisateur

Vous pouvez spécifier un certain nombre de paramètres de configuration pour les widgets à l'aide des métadonnées AppWidgetProviderInfo. Vous pouvez récupérer ces options de configuration, décrites plus en détail dans les sections suivantes, à partir de l'objet AppWidgetProviderInfo associé à un fournisseur de widgets.

Quelle que soit la version d'Android que vous ciblez, tous les hôtes ont les responsabilités suivantes:

• Lorsque vous ajoutez un widget, attribuez son ID comme décrit précédemment. Lorsqu'un widget est supprimé de l'hôte, appelez deleteAppWidgetId() pour désallouer l'ID du widget.

• Lorsque vous ajoutez un widget, vérifiez si l'activité de configuration doit être lancée. En règle générale, l'hôte doit lancer l'activité de configuration du widget si elle existe et qu'elle n'est pas marquée comme facultative en spécifiant les options configuration_optional et reconfigurable. Pour en savoir plus, consultez Mettre à jour le widget à partir de l'activité de configuration. Cette étape est nécessaire pour de nombreux widgets avant de pouvoir s'afficher.

• Les widgets spécifient une largeur et une hauteur par défaut dans les métadonnées AppWidgetProviderInfo. Ces valeurs sont définies dans des cellules à partir d'Android 12 si targetCellWidth et targetCellHeight sont spécifiés, ou dans des dps si seuls minWidth et minHeight sont spécifiés. Consultez la section Attributs de dimensionnement des widgets.

  Assurez-vous que le widget est disposé avec au moins ce nombre de dp. Par exemple, de nombreux hôtes alignent les icônes et les widgets dans une grille. Dans ce scénario, l'hôte ajoute par défaut le widget en utilisant le nombre minimal de cellules conformes aux contraintes minWidth et minHeight.

En plus des exigences listées dans la section précédente, des versions de plate-forme spécifiques introduisent des fonctionnalités qui placent de nouvelles responsabilités sur l'hôte.

Déterminez votre approche en fonction de la version d'Android ciblée.

Android 12

Android 12 (niveau d'API 31) regroupe un List<SizeF> supplémentaire qui contient la liste des tailles possibles en dps qu'une instance de widget peut prendre dans le bundle d'options. Le nombre de tailles fournies dépend de l'implémentation de l'hôte. Les hôtes proposent généralement deux tailles pour les téléphones (portrait et paysage) et quatre tailles pour les pliables.

Le nombre d'RemoteViews différents qu'un AppWidgetProvider peut fournir à RemoteViews est limité à MAX_INIT_VIEW_COUNT (16). Étant donné que les objets AppWidgetProvider mappent un objet RemoteViews à chaque taille dans List<SizeF>, ne fournissez pas plus de MAX_INIT_VIEW_COUNT tailles.

Android 12 introduit également les attributs maxResizeWidth et maxResizeHeight en dps. Nous vous recommandons de ne pas dépasser la taille spécifiée par un widget utilisant au moins l'un de ces attributs.

Ressources supplémentaires

• Consultez la documentation de référence sur Glance.