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 des widgets) pour un accès rapide au contenu. Si vous créez un remplacement d'écran d'accueil ou une application similaire, vous pouvez également permettre à l'utilisateur d'intégrer des widgets en implémentant AppWidgetHost. La plupart des applications n'ont pas besoin de le faire, mais si vous créez votre propre hôte, il est important de comprendre les obligations contractuelles auxquelles un hôte accepte implicitement.

Cette page se concentre 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 une présentation des classes et des concepts clés impliqués dans l'implémentation d'un AppWidgetHost personnalisé :

  • Hôte de widget d'application : le 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 propre package de l'hôte. Cet ID est conservé pour toutes les utilisations de l'hôte. L'ID est généralement une valeur codée en dur que vous attribuez dans votre application.

  • ID de widget d'application : chaque instance de widget reçoit un ID unique au moment de la liaison. Consultez bindAppWidgetIdIfAllowed() et, pour en savoir plus, la section Lier des widgets ci-dessous. L'hôte obtient l'ID unique à l'aide de allocateAppWidgetId(). Cet ID est conservé 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 d'application.

  • Vue de l'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 un 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 les setColorResources() et resetColorResources() méthodes pour gérer les couleurs surchargées de manière dynamique. L'hôte est responsable de la fourniture des couleurs à ces méthodes.

  • Bundle d'options : AppWidgetHost utilise le bundle d'options pour communiquer des informations à AppWidgetProvider sur la façon dont le widget est affiché (par exemple, la liste des plages de tailles) et s'il 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 son mode et de son emplacement d'affichage. Vous pouvez utiliser updateAppWidgetOptions() et updateAppWidgetSize() pour modifier le bundle d'un widget. Ces deux méthodes déclenchent le onAppWidgetOptionsChanged() rappel sur AppWidgetProvider.

Lier des widgets

Lorsqu'un utilisateur ajoute un widget à un hôte, un processus appelé liaison 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 interface utilisateur personnalisée pour la liaison. Pour utiliser ce processus, votre application doit déclarer l' BIND_APPWIDGET autorisation 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. Lors 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 bindAppWidgetIdIfAllowed() méthode. Si bindAppWidgetIdIfAllowed() renvoie false, votre application doit afficher une boîte de dialogue invitant l'utilisateur à accorder l'autorisation : "Autoriser" pour l'ajout du widget actuel ou "Toujours autoriser" pour couvrir tous les futurs ajouts de widgets.

Cet extrait montre comment afficher la boîte de dialogue :

Kotlin

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)

Java

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 qu'un utilisateur ajoute nécessite une configuration. Pour en savoir plus, consultez Permettre aux utilisateurs de configurer des widgets d'application.

Responsabilités de l'hôte

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

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

  • Lors de l'ajout d'un widget, allouez l'ID du widget comme décrit précédemment. Lorsqu'un widget est supprimé de l'hôte, appelez deleteAppWidgetId() pour désallouer l'ID du widget.

  • Lors de l'ajout d'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 n'est pas marquée comme facultative en spécifiant à la fois les indicateurs 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 qu'ils ne puissent 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 en cellules (à partir d'Android 12, si targetCellWidth et targetCellHeight sont spécifiés) ou en dp si seuls minWidth et minHeight sont spécifiés. Consultez les attributs de dimensionnement des widgets.

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

Outre les exigences listées dans la section précédente, certaines versions de la plate-forme introduisent des fonctionnalités qui imposent de nouvelles responsabilités à l'hôte.

Déterminer 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 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 fournissent généralement deux tailles pour les téléphones (portrait et paysage) et quatre tailles pour les appareils pliables.

Le nombre de différents RemoteViews 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 de la List<SizeF>, ne fournissez pas plus de MAX_INIT_VIEW_COUNT tailles.

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

Ressources supplémentaires

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