Mises en page standards des widgets

Pour créer des mises en page de widgets efficaces, commencez par identifier votre contenu principal. Votre mise en page détermine la façon dont les informations et les éléments interactifs sont organisés dans votre widget. Android propose plusieurs mises en page prédéfinies pour les barres d'outils, le texte, les widgets de type liste et grille afin de simplifier ce processus.

Texte

Les mises en page de texte sont idéales pour afficher des informations concises. Améliorez l'attrait visuel de votre widget en incluant éventuellement une image à côté du texte.

Texte uniquement

Idéal pour les titres, les mises à jour de statut, les brèves descriptions ou tout scénario dans lequel une seule ligne de texte transmet efficacement le message.

Textes et images

Incluez une image pour un impact visuel accru. Pour en savoir plus sur l'adaptation de cette mise en page à différentes tailles d'écran, consultez Points d'arrêt.

Barres d'outils

Utilisez des mises en page de barre d'outils pour permettre aux utilisateurs d'accéder rapidement aux tâches fréquemment utilisées dans votre application, dans une mise en page flexible qui s'adapte à toutes les tailles de widget.

Barre d'outils de recherche

La mise en page de la barre d'outils de recherche est intentionnellement conçue pour attirer l'attention sur la recherche en tant qu'action principale dans la barre d'outils. Des boutons pratiques supplémentaires peuvent permettre d'accéder rapidement aux fonctions fréquemment utilisées.

Barre d'outils

Les barres d'outils présentent la marque de l'application, suivie de boutons pour les tâches les plus courantes, qui sont idéaux pour les paramètres activables/désactivables ou les liens vers des tâches. Lors du redimensionnement, les options les moins courantes peuvent être masquées au profit des actions les plus courantes. Utilisez Points d'arrêt pour ajouter un nouveau bouton cliquable de 48 dp minimum lorsqu'il y a de la place.

Listes

Utilisez des mises en page de liste pour organiser plusieurs éléments dans un format clair et facile à parcourir. C'est idéal pour les titres d'actualités, les listes de tâches ou les messages. Organisez le contenu dans une liste structurée et facile à parcourir. Choisissez entre une présentation avec ou sans conteneur en fonction de vos besoins en termes de contenu.

Liste de texte et d'images

Les listes de texte et d'images lisibles sont idéales pour présenter plusieurs types de contenus, comme des titres d'actualités, des playlists avec des pochettes d'album ou des messages.

Checklist

La mise en page de la checklist est idéale pour afficher les tâches, en fournissant des cibles tactiles claires permettant aux utilisateurs de marquer rapidement les éléments comme terminés.

Liste des actions

Regroupez les commandes de manière intuitive avec des listes d'actions, où les états visuels activé/désactivé fournissent un retour immédiat sur l'état des éléments.

Image bord à bord

Idéal pour afficher des images immersives sans marge sur Android 17 et versions ultérieures, cette mise en page utilise le défilement par accroche pour s'assurer que chaque élément enfant s'aligne parfaitement sur la hauteur du conteneur du widget.

Grille

Présentez des images dans une grille compacte, flexible et visuellement riche, avec des libellés facultatifs. Utilisez des colonnes et des lignes qui s'adaptent à différentes tailles d'écran.

Image uniquement

Créez des galeries d'images défilables et visuellement attrayantes à l'aide de grilles d'images uniquement. Les lignes et les colonnes s'adaptent automatiquement à différentes tailles d'écran pour une présentation optimale.

Image et texte

Vous pouvez également ajouter des libellés et des descriptions textuels pour enrichir le contenu de votre grille d'images avec du contexte et des informations supplémentaires.

Exemples de code

Le tableau suivant mappe chaque mise en page canonique à son implémentation Jetpack Glance correspondante dans le dépôt GitHub des exemples de plate-forme Android.

Mise en page canonique Fichiers de référence Conseils
Mise en page de la liste des actions
  • Gérez les actions des éléments de liste avec les rappels d'action Glance et assurez-vous que l'état est correctement mis à jour.
Vérifier la mise en page de la liste
  • Implémentez l'activation/la désactivation de l'état des cases à cocher à l'aide de paramètres d'action ou de rappels pour mettre à jour les éléments de la collection.
  • Utilisez des rappels d'action Glance, tels que `actionRunCallback`, `ActionCallback(actionParametersOf(...))` ou `actionStartActivity(...)`, pour les paramètres `onClick` du widget afin de gérer les événements de clic, comme l'appui sur une case à cocher.
Mise en page expressive de la barre d'outils
  • Évitez les erreurs d'importation de `ColorProvider` : importez `androidx.glance.unit.ColorProvider` et utilisez `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Utilisez directement `GlanceModifier.background(Color)` pour les couleurs d'arrière-plan unies plutôt que `ColorProvider`.
Mise en page en grille d'images
  • Utilisez des couleurs unies (`GlanceModifier.background`) ou des drawables locaux pour les éléments d'image, sauf si une bibliothèque de chargement d'images est configurée ou demandée.
Mise en page "Liste de texte avec image"
  • Cas d'utilisation courants : flux d'actualités, listes d'articles, historiques d'entraînement, flux de messages et listes de miniatures verticales.
  • Équilibrer la hauteur des lignes de la liste et le texte tronqué lorsque des miniatures sont combinées à du texte principal/secondaire.
Mise en page de texte long
  • Si vous multipliez des valeurs Dp, telles que `2 * padding`, importez `androidx.compose.ui.unit.times`.
  • Respectez les règles de dimensionnement : assurez-vous que les dimensions de `dimens.xml` sont utilisées pour la mise à l'échelle de la typographie et des marges intérieures.
Mise en page de la barre d'outils de recherche
  • Évitez les erreurs d'importation de `ColorProvider` : importez `androidx.glance.unit.ColorProvider` et utilisez `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Utilisez directement `GlanceModifier.background(Color)` pour les couleurs d'arrière-plan unies plutôt que ColorProvider.
Mise en page avec image bord à bord / Défilement par points d'arrêt
  • Définissez `verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)` sur LazyColumn pour le défilement par alignement.
  • Si vous implémentez le défilement par paliers, vous devez utiliser Glance 1.3.0-alpha02 ou version ultérieure, le SDK de compilation 37 (Baklava) ou version ultérieure, ainsi que le plug-in Android Gradle (AGP) 9.1.0 ou version ultérieure.
  • Définissez `override val sizeMode: SizeMode = SizeMode.Exact` dans la classe du fournisseur de widget.
Mise en page standard de la barre d'outils
  • Consultez la section "Dépannage" pour éviter les erreurs d'importation de `ColorProvider` : utilisez `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Utilisez directement `GlanceModifier.background(Color)` pour les couleurs d'arrière-plan unies plutôt que `ColorProvider`.
Mise en page "Texte avec image"
  • Suivez les règles de dimensionnement des mises en page responsives pour afficher le texte et l'image côte à côte ou les empiler en fonction des dimensions disponibles du widget.