Les widgets d'application sont des vues d'application miniatures que vous pouvez intégrer dans d'autres applications, comme l'écran d'accueil, et recevoir des mises à jour régulières. Ces vues sont appelées widgets dans l'interface utilisateur, et 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 montre un exemple de widget de musique :
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 la section Créer un hôte de widget.
Pour en savoir plus sur la conception de votre widget, consultez la présentation des widgets d'application.
Composants de 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
AppWidgetProviderclasse.AppWidgetProviderInfoest défini en XML, comme décrit dans ce document. AppWidgetProviderclasse- Définit les méthodes de base qui vous permettent d'interagir de manière programmatique avec le widget. Vous recevez ainsi 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 global de traitement 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 Permettre aux utilisateurs de reconfigurer les widgets placés.
- Dans 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 widget 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 (Compose en premier) dans la documentation Glance.
Utiliser la classe AppWidgetProvider pour gérer les diffusions de widgets
Les mécanismes de broadcast receiver de la plate-forme, les filtres de déclaration de fichier manifeste et les boucles d'événements de cycle de vie sont unifiés sous la plate-forme. Dans le développement Compose en premier, 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 (Compose en premier) dans la documentation Glance.
Créer la mise en page du widget
Vous devez définir une mise en page initiale pour votre widget en 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 mise en page ou de widget 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, qui est 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.
Compatibilité avec le comportement avec état
Android 12 ajoute la compatibilité 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'inscrire aux é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 : une ciblant les appareils équipés d'Android 12 ou
version ultérieure dans res/layout-v31, et l'autre ciblant les versions précédentes
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 en premier, cela peut être défini de manière dynamique dans Kotlin, en plus des ressources de thème personnalisées.
Pour implémenter des rayons d'angle ou configurer des styles dynamiques pour les anciens appareils Android, consultez la section Implémenter des angles arrondis (Compose en premier) dans la documentation Glance.