Diseños de widgets canónicos

Para crear diseños de widgets eficaces, primero identifica tu contenido principal. El diseño dicta cómo se organizan la información y los elementos interactivos dentro del widget. Android ofrece varios diseños precompilados para barras de herramientas, texto, listas y widgets de tipo cuadrícula para optimizar este proceso.

Texto

Los diseños de texto son ideales para mostrar información concisa. Para mejorar el atractivo visual del widget, puedes incluir una imagen junto al texto.

Solo texto

Ideal para títulos, actualizaciones de estado, descripciones breves o cualquier situación en la que una sola línea de texto transmita el mensaje de manera eficaz.

Texto con imágenes

Incluye una imagen para agregar impacto visual. Para obtener más información, consulta Puntos de interrupción para aprender a adaptar este diseño a diferentes tamaños de pantalla.

Barras de herramientas

Usa diseños de barras de herramientas para proporcionar a los usuarios acceso rápido a las tareas que se usan con frecuencia en tu app, en un diseño flexible que se adapta a los tamaños de los widgets.

Barra de herramientas de búsqueda

Un diseño de barra de herramientas de búsqueda está diseñado intencionalmente para centrar la atención en la búsqueda como acción principal en la barra de herramientas. Los botones prácticos adicionales pueden proporcionar acceso rápido a las funciones que se usan con frecuencia.

Barra de herramientas

Las barras de herramientas presentan la marca de la app seguida de botones para las tareas más usadas que son ideales para la configuración conmutable o los vínculos de tareas. Cuando se cambia el tamaño, las opciones que se usan con menos frecuencia se pueden ocultar en favor de las acciones más comunes. Usa puntos de interrupción para agregar un nuevo botón presionable de 48 dp mínimo cuando haya espacio.

Listas

Usa diseños de listas para organizar varios elementos en un formato claro y legible. Esto es ideal para titulares de noticias, listas de tareas pendientes o mensajes. Organiza el contenido en una lista estructurada y legible. Elige entre la presentación en contenedores o sin contenedores según tus necesidades de contenido.

Lista de texto con imágenes

Las listas de texto con imágenes legibles son perfectas para mostrar varios tipos de contenido, como titulares de noticias, playlists con portadas de álbumes o mensajes.

Lista de tareas

El diseño de la lista de tareas es perfecto para mostrar tareas y proporcionar objetivos táctiles claros para que los usuarios marquen rápidamente los elementos como completados.

Lista de acciones

Proporciona una agrupación de control intuitiva con listas de acciones, en las que los estados visuales de activación y desactivación ofrecen comentarios inmediatos sobre los estados de los elementos.

Imagen a sangre completa

Ideal para mostrar imágenes envolventes a sangre completa en Android 17 y versiones posteriores, este diseño usa el desplazamiento rápido para garantizar que cada elemento secundario se alinee perfectamente con la altura del contenedor del widget.

Cuadrícula

Presenta imágenes en una cuadrícula compacta, flexible y visualmente enriquecida con etiquetas opcionales. Usa columnas y filas que se adapten a diferentes tamaños de pantalla.

Solo imagen

Crea galerías de imágenes desplazables y visualmente impactantes con cuadrículas solo de imágenes. Las filas y las columnas se adaptan automáticamente a varios tamaños de pantalla para una presentación óptima.

Imagen con texto

También puedes incorporar etiquetas y descripciones de texto, lo que enriquece el contenido de la cuadrícula de imágenes con contexto e información adicionales.

Muestras de código

En la siguiente tabla, se asigna cada diseño canónico a su implementación correspondiente de Jetpack Glance en el repositorio de GitHub de Android Platform Samples.

Diseño canónico Archivos de referencia Orientación
Diseño de lista de acciones
  • Controla las acciones de los elementos de la lista con devoluciones de llamada de acción de Glance y garantiza las actualizaciones de estado adecuadas.
Diseño de lista de tareas
  • Implementa la activación y desactivación del estado de la casilla de verificación con parámetros de acción o devoluciones de llamada para actualizar los elementos de la colección.
  • Usa devoluciones de llamada de acción de Glance, como `actionRunCallback`, `ActionCallback(actionParametersOf(...))` o `actionStartActivity(...)`, para los parámetros `onClick` del widget para controlar eventos de clic, como presionar una casilla de verificación.
Diseño de barra de herramientas expresiva
  • Evita errores de importación de `ColorProvider`: importa `androidx.glance.unit.ColorProvider` y usa `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Usa `GlanceModifier.background(Color)` directamente para colores de fondo sólidos en lugar de `ColorProvider`.
Diseño de cuadrícula de imágenes
  • Usa colores sólidos (`GlanceModifier.background`) o elementos de diseño locales para elementos de imagen, a menos que se configure o solicite una biblioteca de carga de imágenes.
Diseño de lista de texto con imágenes
  • Casos de uso comunes: feeds de noticias, listas de artículos, historiales de entrenamiento, feeds de mensajes y listas de miniaturas verticales.
  • Equilibra la altura de la fila de la lista y el recorte de texto cuando combines imágenes en miniatura con texto primario o secundario.
Diseño de texto largo
  • Si multiplicas valores `Dp`, como `2 * padding`, importa `androidx.compose.ui.unit.times`.
  • Sigue las reglas de tamaño: asegúrate de que las dimensiones de `dimens.xml` se usen para el padding y el ajuste de escala de la tipografía.
Diseño de barra de herramientas de búsqueda
  • Evita errores de importación de `ColorProvider`: importa `androidx.glance.unit.ColorProvider` y usa `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Usa `GlanceModifier.background(Color)` directamente para colores de fondo sólidos en lugar de ColorProvider.
Diseño de imagen a sangre completa o desplazamiento rápido
  • Configura `verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)` en LazyColumn para el desplazamiento rápido.
  • Si implementas el desplazamiento rápido, se requiere Glance 1.3.0-alpha02 o una versión posterior, compilar el SDK 37 (Baklava) o una versión posterior, y el complemento de Android para Gradle (AGP) 9.1.0 o una versión posterior.
  • Configura `override val sizeMode: SizeMode = SizeMode.Exact` en la clase de proveedor de widgets.
Diseño de barra de herramientas estándar
  • Consulta Solución de problemas para evitar errores de importación de `ColorProvider`: usa `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Usa `GlanceModifier.background(Color)` directamente para colores de fondo sólidos en lugar de `ColorProvider`.
Diseño de texto con imágenes
  • Sigue las reglas de tamaño de diseño responsivo para adaptar el texto y la imagen uno al lado del otro o apilados según las dimensiones disponibles del widget.