Diseños de widgets canónicos

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

Texto

Los diseños de texto son ideales para mostrar información concisa. Mejora el atractivo visual de tu widget incluyendo, de forma opcional, 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 generar un mayor impacto visual. Para obtener más información, consulta Puntos de interrupción y descubre cómo adaptar este diseño a diferentes tamaños de pantalla.

Barras de herramientas

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

Barra de herramientas de búsqueda

El diseño de la barra de herramientas de búsqueda se creó intencionalmente para enfocar la búsqueda como la acción principal en la barra de herramientas. Los botones adicionales prácticos 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 activable 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 Breakpoints para agregar un nuevo botón que se pueda presionar de 48 dp como mínimo cuando haya espacio.

Listas

Usa diseños de lista para organizar varios elementos en un formato claro y fácil de leer. Es ideal para titulares de noticias, listas de tareas o mensajes. Organiza el contenido en una lista estructurada y fácil de leer. Elige entre la presentación con o sin contenedor según tus necesidades de contenido.

Lista de imágenes y texto

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

Lista de tareas

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

Lista de acciones

Proporciona una agrupación de controles 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 y de sangrado completo en Android 17 y versiones posteriores, este diseño usa el desplazamiento de ajuste 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 y texto

También puedes incorporar etiquetas y descripciones de texto, lo que enriquecerá el contenido de tu 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 muestras de la plataforma de Android.

Diseño canónico Archivos de referencia Orientación
Diseño de la lista de acciones
  • Controla las acciones de los elementos de la lista con devoluciones de llamada de acciones de Glance y garantiza las actualizaciones de estado adecuadas.
Diseño de lista de verificación
  • Implementa la activación o 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 acciones de Glance, como `actionRunCallback`, `ActionCallback(actionParametersOf(...))` o `actionStartActivity(...)`, para los parámetros `onClick` del widget y controlar eventos de clic, como cuando se presiona una casilla de verificación.
Diseño expresivo de la barra de herramientas
  • 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 los 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 drawable locales para los 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 principal o secundario.
Diseño de texto largo
  • Si multiplicas valores de "Dp", como "2 * padding", importa "androidx.compose.ui.unit.times".
  • Sigue las reglas de tamaño: Asegúrate de que se usen las dimensiones de `dimens.xml` para el padding y el ajuste de escala de la tipografía.
Diseño de la 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 / Desplazamiento de ajuste
  • Establece `verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)` en LazyColumn para el desplazamiento rápido.
  • Si implementas el desplazamiento con ajuste, se requieren Glance 1.3.0-alpha02 o una versión posterior, el SDK de compilación 37 (Baklava) o una versión posterior, y el complemento de Android para Gradle (AGP) 9.1.0 o una versión posterior.
  • Establece `override val sizeMode: SizeMode = SizeMode.Exact` en la clase del 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 los colores de fondo sólidos en lugar de `ColorProvider`.
Diseño de texto con imagen
  • Sigue las reglas de tamaño del diseño responsivo para colocar texto e imágenes uno al lado del otro o apilados según las dimensiones disponibles del widget.