Las vistas previas generadas de widgets 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 los widgets basados en Glance. Si tu widget se implementó con RemoteViews, consulta Cómo agregar vistas previas al selector de widgets.
Para mejorar la experiencia del selector de widgets de tu app para los widgets de Glance, proporciona una vista previa del widget generada con GlanceAppWidget.providePreview en dispositivos con Android 15 y versiones posteriores, y especifica un previewImage para versiones anteriores y como alternativa en Android 15 y versiones posteriores si no hay disponible una vista previa generada.
Para obtener más información, consulta Enriquece tu app con actualizaciones en vivo y widgets en YouTube.
Configura tu app para obtener vistas previas de widgets generados
Para mostrar vistas previas de widgets generados en dispositivos con Android 15 o versiones posteriores, primero establece el valor compileSdk en 35 o una versión posterior en el archivo build.gradle del módulo para poder proporcionar RemoteViews al selector de widgets.
Luego, las apps pueden usar setWidgetPreview en GlanceAppWidgetManager. Para evitar abusos y mitigar los problemas de funcionamiento del sistema, la API de setWidgetPreview tiene un 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 creados con Jetpack Glance, haz lo siguiente:
Anula la función
GlanceAppWidget.providePreviewpara proporcionar el contenido componible de la vista previa. Al igual que enprovideGlance, carga los datos de tu app y pásalos al elemento componible de contenido del widget para que la vista previa muestre datos precisos. A diferencia deprovideGlance, esta es una sola composición sin recomposición ni efectos.Llama a
GlanceAppWidgetManager.setWidgetPreviewspara generar y publicar la vista previa.
El sistema no proporciona una devolución de llamada 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 inicie 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 la cadencia que elijas.
Soluciona problemas de las vistas previas generadas
Un problema común es que, después de generar una vista previa, es posible que falten imágenes, íconos o 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 soltar se define con targetCellWidth y targetCellHeight, si se especifican, o con minWidth y minHeight en el archivo de información del proveedor del widget de la app.
Esto ocurre 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 del widget de la app para determinar qué elementos componibles dibujar.
Para corregir este problema, anula previewSizeMode en tu GlanceAppWidget y configúralo como SizeMode.Responsive, proporcionando un conjunto de valores de 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 un 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 y versiones posteriores, especifica el atributo previewImage.
Si cambias el aspecto del widget, actualiza la imagen de vista previa.