Créer un widget simple

Essayer Compose
Jetpack Compose est le kit d'outils d'UI recommandé pour Android. Découvrez comment créer des widgets à l'aide d'API de style Compose.
Jetpack Glance →

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 sont mises à jour régulièrement. 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 montre un exemple de widget musical :

Exemple de widget musical
Figure 1. Exemple de widget de musique.

Ce document explique comment publier un widget à l'aide d'un fournisseur de widgets. Pour savoir comment créer 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 :

Objet AppWidgetProviderInfo
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. AppWidgetProviderInfo est 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. Il vous permet de recevoir des diffusions lorsque le widget est mis à jour, activé, désactivé ou supprimé. Vous déclarez AppWidgetProvider dans 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 au flux global de traitement des widgets d'application.

Flux de traitement des widgets d'application
Figure 2. Flux de traitement des widgets d'application.

Si votre widget nécessite une configuration par l'utilisateur, implémentez l'activité de configuration du widget d'application. Cette activité permet aux utilisateurs de modifier les paramètres des widgets (par exemple, le fuseau horaire d'un widget d'horloge).

Nous vous recommandons également les améliorations suivantes : dispositions flexibles des widgets, 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 la même 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 la section XML AppWidgetProviderInfo dans la documentation Glance.

Utiliser la classe AppWidgetProvider pour gérer les diffusions de widgets

Les mécanismes de récepteur de diffusion 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-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 dans 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.

Créer 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 mises en page ou de widgets 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 prise en charge du 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.

Exemple de widget de liste de courses montrant un comportement avec état
Figure 3. Exemple de comportement avec état.

L'exemple de code suivant montre comment implémenter ces composants.

Kotlin

// 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)
)

Java

// 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 versions antérieures d'Android 11 ou version antérieure dans le dossier res/layout par défaut.

Implémenter des angles arrondis

Le calcul des rayons proportionnels interne et externe de l'arrière-plan est standard et partagé. Dans le développement Compose-first, 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 de la documentation Glance.