Las vistas previas generadas de los 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.
Para mejorar la experiencia del selector de widgets de tu app, proporciona una vista previa del widget generada en dispositivos con Android 15 y versiones posteriores, una vista previa del widget escalada (especificando un previewLayout) para dispositivos con Android 12 a Android 14 y un previewImage para versiones anteriores.
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 un dispositivo con Android 15 o versiones posteriores, primero establece el valor de 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 o AppWidgetManager. Para evitar el abuso y mitigar los problemas de salud 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 creados con Jetpack Glance, haz lo siguiente:
Anula la función
GlanceAppWidget.providePreviewpara proporcionar el contenido componible de la vista previa. Al igual que lo harías enprovideGlance, carga los datos de tu app y pásalos al elemento componible de contenido del widget para asegurarte de 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.
Solución de 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 1 o 2 tamaños a partir del mínimo y siguiendo los puntos de interrupción de tu widget. Especifica al menos una imagen para la retrocompatibilidad. 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.
Genera una vista previa actualizada sin Jetpack Glance
Puedes usar RemoteViews sin la función de un vistazo. En el siguiente ejemplo, se carga un recurso de diseño de un widget XML y se establece como vista previa. Se requiere un parámetro de configuración de compilación compileSdk de 35 o posterior para que setWidgetPreview se muestre como un método en este fragmento.
AppWidgetManager.getInstance(appContext).setWidgetPreview(
ComponentName(
appContext,
ExampleAppWidgetReceiver::class.java
),
AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
RemoteViews("com.example", R.layout.widget_preview)
)
Cómo agregar vistas previas escalables de widgets al selector del widget
A partir de Android 12, la vista previa del widget que se muestra en el selector del widget es escalable. Lo proporcionarás como un diseño XML configurado en el tamaño predeterminado del widget. Anteriormente, la vista previa del widget era un recurso de diseño estático que, en algunos casos, causaba que las vistas previas no mostraran con exactitud los widgets después de que se agregaban a la pantalla principal.
Para implementar vistas previas escalables de widgets, usa el atributo previewLayout del elemento appwidget-provider para proporcionar un diseño XML en su lugar:
<appwidget-provider
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
Te recomendamos que uses el mismo diseño que el del widget real, con valores realistas predeterminados o de las pruebas. La mayoría de las apps usan el mismo previewLayout y initialLayout. Para obtener orientación sobre cómo crear diseños de vista previa precisos, consulta la siguiente sección de esta página.
Te recomendamos que especifiques los atributos previewLayout y previewImage para que tu app pueda recurrir a previewImage si el dispositivo del usuario no admite previewLayout. El atributo previewLayout tiene prioridad sobre el atributo previewImage.
Retrocompatibilidad con vistas previas de widgets
Para permitir que los selectores de widgets en Android 11 (nivel de API 30) o versiones anteriores muestren vistas previas de tu widget, o como alternativa para las vistas previas generadas, especifica el atributo previewImage.
Si cambias el aspecto del widget, actualiza la imagen de vista previa.
Crea vistas previas precisas que incluyan elementos dinámicos
En esta sección, se explica el enfoque recomendado para mostrar varios elementos en una vista previa de un widget con una vista de colección, es decir, un widget que usa un ListView, GridView o StackView. Esto no se aplica a las vistas previas de widgets generadas.
Si tu widget usa una de estas vistas, crear una vista previa escalable proporcionando directamente el diseño del widget real degrada la experiencia cuando la vista previa del widget no muestra elementos. Esto ocurre porque los datos de la vista de recopilación se establecen de forma dinámica en el tiempo de ejecución y se ven similares a la imagen que se muestra en la figura 1.
Para que las vistas previas de los widgets con vistas de colección se muestren correctamente en el selector de widgets, te recomendamos que mantengas un archivo de diseño independiente designado solo para la vista previa. Este archivo de diseño independiente debe incluir lo siguiente:
- Es el diseño real del widget.
- Es una vista de colección de marcador de posición con elementos falsos. Por ejemplo, puedes simular un
ListViewproporcionando un marcador de posiciónLinearLayoutcon varios elementos de lista falsos.
Para ilustrar un ejemplo de un ListView, comienza con un archivo de diseño independiente:
// res/layout/widget_preview.xml
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="@drawable/widget_background"
android:orientation="vertical">
// Include the actual widget layout that contains ListView.
<include
layout="@layout/widget_view"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
// The number of fake items you include depends on the values you provide
// for minHeight or targetCellHeight in the AppWidgetProviderInfo
// definition.
<TextView android:text="@string/fake_item1"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginVertical="?attr/appWidgetInternalPadding" />
<TextView android:text="@string/fake_item2"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginVertical="?attr/appWidgetInternalPadding" />
</LinearLayout>
Especifica el archivo de diseño de vista previa cuando proporciones el atributo previewLayout de los metadatos AppWidgetProviderInfo. Aún debes especificar el diseño real del widget para el atributo initialLayout y usar el diseño real del widget cuando construyas un RemoteViews en el tiempo de ejecución.
<appwidget-provider
previewLayout="@layout/widget_previe"
initialLayout="@layout/widget_view" />
Elementos de lista complejos
El ejemplo de la sección anterior proporciona elementos de lista falsos, ya que los elementos de lista son objetos TextView. Puede ser más complejo proporcionar elementos falsos si los diseños son complejos.
Considera un elemento de lista que se define en widget_list_item.xml y consta de dos objetos TextView:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="wrap_content">
<TextView android:id="@id/title"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:text="@string/fake_title" />
<TextView android:id="@id/content"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:text="@string/fake_content" />
</LinearLayout>
Para proporcionar elementos de lista falsos, puedes incluir el diseño varias veces, pero esto hace que cada elemento de lista sea idéntico. Para proporcionar elementos de lista únicos, sigue estos pasos:
Crea un conjunto de atributos para los valores de texto:
<resources> <attr name="widgetTitle" format="string" /> <attr name="widgetContent" format="string" /> </resources>Usa estos atributos para establecer el texto:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="wrap_content"> <TextView android:id="@id/title" android:layout_width="match_parent" android:layout_height="wrap_content" android:text="?widgetTitle" /> <TextView android:id="@id/content" android:layout_width="match_parent" android:layout_height="wrap_content" android:text="?widgetContent" /> </LinearLayout>Crea todos los estilos que sean necesarios para la vista previa. Redefine los valores en cada estilo:
<resources> <style name="Theme.Widget.ListItem"> <item name="widgetTitle"></item> <item name="widgetContent"></item> </style> <style name="Theme.Widget.ListItem.Preview1"> <item name="widgetTitle">Fake Title 1</item> <item name="widgetContent">Fake content 1</item> </style> <style name="Theme.Widget.ListItem.Preview2"> <item name="widgetTitle">Fake title 2</item> <item name="widgetContent">Fake content 2</item> </style> </resources>Aplica los diseños a los elementos falsos en el diseño de vista previa:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="wrap_content" ...> <include layout="@layout/widget_view" ... /> <include layout="@layout/widget_list_item" android:theme="@style/Theme.Widget.ListItem.Preview1" /> <include layout="@layout/widget_list_item" android:theme="@style/Theme.Widget.ListItem.Preview2" /> </LinearLayout>