Les widgets d'application sont des vues d'application miniatures que vous pouvez intégrer à d'autres applications (comme l'écran d'accueil) et qui reçoivent des mises à jour périodiques. Ces vues sont appelées widgets dans l'interface utilisateur. Vous pouvez en publier une avec un fournisseur de widgets d'application (ou fournisseur de widgets). Un composant d'application qui contient d'autres widgets est appelé hôte de widget d'application (ou hôte de widget). La figure 1 présente un exemple de widget musical :
Ce document explique comment publier un widget à l'aide d'un fournisseur de widgets. Pour en savoir plus sur la création de votre propre AppWidgetHost pour héberger des widgets d'application, consultez Créer un hôte de widget.
Pour savoir comment concevoir votre widget, consultez Présentation des widgets d'application.
Composants du widget
Pour créer un widget, vous avez besoin des composants de base suivants :
AppWidgetProviderInfoobjet- Décrit les métadonnées d'un widget, telles que sa mise en page, sa fréquence de mise à jour et sa classe
AppWidgetProvider.AppWidgetProviderInfoest défini en XML, comme décrit dans ce document. - Classe
AppWidgetProvider - Définit les méthodes de base qui vous permettent d'interagir de manière programmatique avec le widget. Grâce à lui, vous recevez des diffusions lorsque le widget est mis à jour, activé, désactivé ou supprimé. Vous déclarez
AppWidgetProviderdans le fichier manifeste, puis vous l'implémentez, comme décrit dans ce document. - Afficher la mise en page
- Définit la mise en page initiale du widget. La mise en page est définie en XML, comme décrit dans ce document.
La figure 2 montre comment ces composants s'intègrent dans le flux de traitement global des widgets d'application.
Si votre widget nécessite une configuration utilisateur, implémentez l'activité de configuration du widget d'application. Cette activité permet aux utilisateurs de modifier les paramètres du widget, par exemple le fuseau horaire d'un widget d'horloge.
- À partir d'Android 12 (niveau d'API 31), vous pouvez fournir une configuration par défaut et permettre aux utilisateurs de reconfigurer le widget ultérieurement. Pour en savoir plus, consultez Utiliser la configuration par défaut du widget et Autoriser les utilisateurs à reconfigurer les widgets placés.
- Sous Android 11 (niveau d'API 30) ou version antérieure, cette activité est lancée chaque fois que l'utilisateur ajoute le widget à son écran d'accueil.
Nous vous recommandons également les améliorations suivantes : mises en page de widgets flexibles, améliorations diverses, widgets avancés, widgets de collection et création d'un hôte de widget.
Déclarer le fichier XML AppWidgetProviderInfo
La définition des paramètres de métadonnées (tels que les tailles de cellule par défaut, les contraintes de redimensionnement et les fréquences de mise à jour) est exactement identique pour les vues traditionnelles et les widgets basés sur Glance.
Pour savoir comment définir et configurer votre fichier XML de métadonnées, consultez la section Déclarer le fichier XML AppWidgetProviderInfo de la documentation Glance.
Utiliser la classe AppWidgetProvider pour gérer les diffusions de widgets
Les mécanismes de broadcast receiver, les filtres de déclaration de fichier manifeste et les boucles d'événements de cycle de vie de la plate-forme sont unifiés sous la plate-forme. Dans le développement Compose-first, ces diffusions sont orchestrées à l'aide du wrapper GlanceAppWidgetReceiver.
Pour savoir comment enregistrer votre récepteur dans le fichier manifeste et implémenter des remplacements de cycle de vie compatibles avec Hilt, consultez la section Utiliser la classe AppWidgetProvider pour gérer les diffusions de la documentation Glance.
Créer la mise en page du widget
Vous devez définir une mise en page initiale pour votre widget au format XML et l'enregistrer dans le répertoire res/layout/ du projet. Pour en savoir plus, consultez les consignes de conception.
La création de la mise en page du widget est simple si vous connaissez les mises en page. Toutefois, sachez que les mises en page des widgets sont basées sur RemoteViews, qui n'est pas compatible avec tous les types de widgets de mise en page ou de vue.
Vous ne pouvez pas utiliser de vues personnalisées ni de sous-classes des vues compatibles avec RemoteViews.
RemoteViews est également compatible avec ViewStub, une View invisible de taille nulle que vous pouvez utiliser pour gonfler, de manière différée, des ressources de mise en page lors de l'exécution.
Prise en charge du comportement avec état
Android 12 est compatible avec le comportement avec état à l'aide des composants existants suivants :
Le widget est toujours sans état. Votre application doit stocker l'état et s'enregistrer pour les événements de changement d'état.
L'exemple de code suivant montre comment implémenter ces composants.
// Check the view. remoteView.setCompoundButtonChecked(R.id.my_checkbox, true) // Check a radio group. remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2) // Listen for check changes. The intent has an extra with the key // EXTRA_CHECKED that specifies the current checked state of the view. remoteView.setOnCheckedChangeResponse( R.id.my_checkbox, RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent) )
Fournissez deux mises en page : l'une ciblant les appareils équipés d'Android 12 ou version ultérieure dans res/layout-v31, et l'autre ciblant les appareils équipés d'Android 11 ou version antérieure dans le dossier res/layout par défaut.
Implémenter des angles arrondis
Le calcul de l'arrière-plan extérieur et des rayons proportionnels intérieurs est standard et partagé. Dans le développement Compose-first, cela peut être défini de manière dynamique en Kotlin, avec des ressources de thème personnalisées.
Pour implémenter des rayons d'angle ou configurer des styles dynamiques pour les appareils Android plus anciens, consultez la section Implémenter des angles arrondis de la documentation Glance.