Cómo agregar vistas previas generadas al selector de widgets

Las vistas previas de widgets generadas te permiten crear vistas previas dinámicas y personalizadas para tus widgets que reflejan con precisión cómo aparecerán en la pantalla principal de un usuario. Se proporcionan a través de una API de envío, lo que significa que tu app proporciona la vista previa en cualquier momento durante su ciclo de vida sin recibir una solicitud explícita del host del widget.

En esta guía, se explica cómo proporcionar vistas previas para widgets basados en Glance. Si tu widget se implementa con RemoteViews, consulta Cómo agregar vistas previas al selector de widgets.

Para mejorar la experiencia del selector de widgets de tu app para widgets de Glance, proporciona una vista previa de widget generada con GlanceAppWidget.providePreview en dispositivos con Android 15 y versiones posteriores, y especifica una previewImage para versiones anteriores y como alternativa en Android 15+ si no hay una vista previa generada disponible.

Para obtener más información, consulta Cómo enriquecer tu app con actualizaciones en vivo y widgets en YouTube.

Configura tu app para obtener vistas previas de widgets generadas

Para mostrar vistas previas de widgets generadas en dispositivos con Android 15 o versiones posteriores, primero establece el compileSdk valor en 35 o versiones posteriores en el archivo build.gradle del módulo para tener la capacidad de proporcionar RemoteViews al selector de widgets.

Luego, las apps pueden usar setWidgetPreview en GlanceAppWidgetManager. Para evitar el abuso y mitigar los problemas de estado del sistema, setWidgetPreview es una API con límite de frecuencia. El límite predeterminado es de aproximadamente dos llamadas por hora.

Genera una vista previa actualizada con Jetpack Glance

Para los widgets compilados con Jetpack Glance, haz lo siguiente:

1. Anula la función GlanceAppWidget.providePreview para proporcionar el contenido componible de la vista previa. Como lo harías en provideGlance, carga los datos de tu app y pásalos al contenido componible del widget para que la vista previa muestre datos precisos. A diferencia de provideGlance, esta es una composición única sin recomposición ni efectos.

2. Llama a GlanceAppWidgetManager.setWidgetPreviews para generar y publicar la vista previa.

No hay una devolución de llamada del sistema para proporcionar vistas previas, por lo que tu app debe decidir cuándo llamar a setWidgetPreviews. La estrategia de actualización depende del caso de uso de tu widget:

• Si el widget tiene información estática o es una acción rápida, establece la vista previa cuando se inicia la app por primera vez.
• Puedes establecer la vista previa una vez que tu app tenga datos, por ejemplo, después de que un usuario acceda o realice la configuración inicial.
• Puedes configurar una tarea periódica para actualizar las vistas previas con una cadencia elegida.

Soluciona problemas de vistas previas generadas

Un problema común es que, después de generar una vista previa, es posible que falten imágenes, íconos u otros elementos componibles en la imagen de vista previa, en relación con el tamaño de colocación del widget. Este tamaño de colocación se define mediante targetCellWidth y targetCellHeight si se especifican, o mediante minWidth y minHeight en el archivo de información del proveedor de widgets de la app.

Esto sucede porque Android, de forma predeterminada, solo renderiza los elementos componibles visibles en el tamaño mínimo del widget. En otras palabras, Android establece previewSizeMode en SizeMode.Single de forma predeterminada. Usa android:minHeight y android:minWidth en el XML de información del proveedor de widgets de la app para determinar qué elementos componibles dibujar.

Para solucionar este problema, anula previewSizeMode en tu GlanceAppWidget y establécelo en SizeMode.Responsive, lo que proporciona un conjunto de valores DpSize. Esto le indica a Android todos los tamaños de diseño que necesita renderizar para la vista previa, lo que garantiza que todos los elementos se muestren correctamente.

Optimiza para factores de forma específicos. Proporciona uno o dos tamaños a partir del mínimo y siguiendo los puntos de interrupción de tu widget. Especifica al menos una previewImage para la retrocompatibilidad. Puedes encontrar los valores de DP mínimos adecuados para diferentes tamaños de cuadrícula en la guía de diseño de widgets.

Retrocompatibilidad con vistas previas de widgets

Para permitir que los selectores de widgets en dispositivos que ejecutan versiones anteriores a Android 15 muestren vistas previas de tu widget o como alternativa para las vistas previas generadas en Android 15+, especifica el previewImage atributo.

Si cambias el aspecto del widget, actualiza la imagen de vista previa.