Créer un hôte de widget

L'écran d'accueil Android, disponible sur la plupart des appareils Android, permet au intégrer des widgets d'application (ou widgets) pour un accès rapide au contenu. Si vous souhaitez remplacer l'écran d'accueil ou application similaire, vous pouvez aussi permettre à l'utilisateur d'intégrer des widgets en implémentant AppWidgetHost Ce n'est pas ce que la plupart des applications doivent faire, mais si vous créez votre propre hôte, important de comprendre les obligations contractuelles qu'un hôte accepte implicitement.

Cette page se concentre sur les responsabilités liées à l'implémentation d'un modèle AppWidgetHost Pour obtenir un exemple spécifique d'implémentation d'un AppWidgetHost, regardez le code source de l'écran d'accueil Android LauncherAppWidgetHost

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

• App widget host (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 AppWidgetHost doit avoir un identifiant unique dans le propre package de l'hôte. Cet ID persiste pour toutes les utilisations de l'hôte. L'ID est généralement une valeur codée en dur que vous attribuer dans votre application.

• App widget ID (ID de widget d'application) : un identifiant unique est attribué à chaque instance de widget à chaque fois. de liaison. Voir bindAppWidgetIdIfAllowed() et, pour plus de détails, la section Liaison de widgets ci-après. La host obtient l'identifiant unique en utilisant allocateAppWidgetId() Cet identifiant est conservé pendant toute la durée de vie du widget jusqu'à ce qu'il soit supprimé du hôte. Tout état spécifique à l'hôte, tel que la taille et l'emplacement d'hébergement : ils doivent être conservés par le package d'hébergement et associés au ID de widget d'application.

• App widget host view (Vue hôte du widget de l'application) : pensez à AppWidgetHostView en tant que cadre que le widget est encapsulé chaque fois qu'il doit être affiché. Un widget est associé à un AppWidgetHostView chaque fois que le widget est gonflé par la hôte.

  • Par défaut, le système crée un AppWidgetHostView, mais l'hôte peut Créez sa propre sous-classe de AppWidgetHostView en l'étendant.
  • À partir d'Android 12 (niveau d'API 31), AppWidgetHostView introduit le la setColorResources() et resetColorResources() de gestion dynamique des couleurs surchargées. L'hôte est responsable de la fourniture des couleurs à ces méthodes.

• Groupe d'options: AppWidgetHost utilise le bundle d'options pour communiquer des informations AppWidgetProvider sur l'affichage du widget, par exemple, liste des plages de tailles, en précisant si est affiché sur un écran de verrouillage ou sur l'écran d'accueil. Ces informations permettent au AppWidgetProvider adapte le contenu et l'apparence du widget en fonction où il est affiché. Vous pouvez utiliser updateAppWidgetOptions() et updateAppWidgetSize() pour modifier le bundle d'un widget. Ces deux méthodes déclenchent onAppWidgetOptionsChanged() à AppWidgetProvider.

Lier des widgets

Lorsqu'un utilisateur ajoute un widget à un hôte, un processus appelé binding se produit. Liaison désigne l'association d'un identifiant de widget d'application particulier à un hôte spécifique et à des AppWidgetProvider spécifiques.

Les API de liaison permettent également à un hôte de fournir une UI personnalisée pour liée. Pour que vous puissiez utiliser ce processus, votre application doit déclarer le 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 accorder explicitement l'autorisation à votre application pour lui permettre d'ajouter un widget à l'hôte. Pour vérifier si votre application autorisée à ajouter le widget, utilisez la bindAppWidgetIdIfAllowed() . Si bindAppWidgetIdIfAllowed() renvoie false, votre application doit afficher une boîte de dialogue invitant l'utilisateur à accorder l'autorisation : "allow" pour le widget actuel 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 Pour en savoir plus, consultez la section Autoriser les utilisateurs à configurer des applications widgets

Responsabilités de l'organisateur

Vous pouvez spécifier un certain nombre de paramètres de configuration pour les widgets à l'aide de la propriété Métadonnées AppWidgetProviderInfo. Vous pouvez récupérer ces options de configuration, qui sont abordées plus en détail dans le dans les sections suivantes, AppWidgetProviderInfo associé à un fournisseur de widgets.

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

• Lorsque vous ajoutez un widget, attribuez son ID comme décrit précédemment. Lorsqu'un 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é. Généralement, l'hôte doit lancer la configuration du widget s'il existe et qu'il n'est pas marqué comme facultatif, en spécifiant à la fois Options configuration_optional et reconfigurable. Voir Mettre à jour le widget à partir de l'activité de configuration pour en savoir plus. 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 AppWidgetProviderInfo de métadonnées. Ces valeurs sont définies dans des cellules, en commençant par Android 12, si targetCellWidth et targetCellHeight sont ou dps si seuls minWidth et minHeight sont spécifiés. Voir Attributs de dimensionnement des widgets.

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

En plus des exigences mentionnées dans la section précédente, versions de plate-forme introduisent des fonctionnalités qui placent de nouvelles responsabilités sur la 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 contenant la liste des tailles possibles en dp 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 ont généralement proposent deux tailles pour les téléphones (portrait et paysage) et quatre tailles pour les appareils pliables.

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

Android 12 présente également maxResizeWidth et maxResizeHeight en dps. Nous vous recommandons d'utiliser au moins l'un de ces attributs ne dépasse pas la taille spécifiée par les attributs.

Ressources supplémentaires

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