Las vistas previas de widgets generadas te permiten crear vistas previas dinámicas y personalizadas para tus widgets que reflejen 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 de 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 de los 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 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 las versiones anteriores y como resguardo en Android 15 y versiones posteriores si no hay una vista previa generada disponible.
Para obtener más información, consulta Enriquece tu app con novedades en tiempo real y widgets en YouTube.
Configura tu app para obtener vistas previas de widgets generados
Para mostrar vistas previas de widgets generadas en dispositivos con Android 15 o versiones posteriores, primero establece el valor de compileSdk en 35 o un valor superior en el archivo build.gradle del módulo para habilitar las vistas previas generadas en el 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
En el caso de los widgets compilados con Jetpack Glance, haz lo siguiente:
Anula la función
GlanceAppWidget.providePreviewpara proporcionar el contenido componible de la vista previa. Como lo harías 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.
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, configura la vista previa cuando se inicie la app por primera vez.
- Puedes configurar 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 frecuencia 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 algún otro elemento componible 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 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, de forma predeterminada, Android 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 se deben dibujar.
Para solucionar este problema, anula previewSizeMode en tu GlanceAppWidget y configúralo como SizeMode.Responsive, proporcionando 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 del widget. Especifica al menos un previewImage para admitir versiones anteriores de Android. Puedes encontrar los valores mínimos de dp adecuados para diferentes tamaños de cuadrícula en la guía de diseño de widgets.
Compatibilidad con versiones anteriores de Android
Para mostrar vistas previas de widgets en dispositivos que ejecutan Android 14 y versiones anteriores, o cuando no hay una vista previa generada disponible en Android 15 y versiones posteriores, especifica el atributo previewImage.
Si cambias la apariencia del widget, actualiza la imagen de vista previa.