Cómo mejorar tu widget

En esta página, se incluyen detalles sobre las mejoras opcionales de widgets que están disponibles a partir de Android 12 (nivel de API 31). Estas funciones son opcionales, pero son fáciles de implementar y mejoran la experiencia de los usuarios con los widgets.

Cómo usar colores dinámicos

A partir de Android 12, un widget puede usar los colores del tema del dispositivo para botones, fondos y otros componentes. Esto proporciona transiciones más fluidas y coherencia en distintos widgets.

Existen dos maneras de lograr colores dinámicos:

Una vez que se establece el tema en el diseño raíz, puedes usar atributos de color comunes en la raíz o en cualquiera de sus elementos secundarios para captar los colores dinámicos.

Estos son algunos ejemplos de atributos de color que puedes usar:

  • ?attr/primary
  • ?attr/primaryContainer
  • ?attr/onPrimary
  • ?attr/onPrimaryContainer

En el siguiente ejemplo, que usa el tema Material 3, el color del tema del dispositivo es "morado". El color de los elementos destacados y el fondo del widget se adaptan a los modos claro y oscuro, como se muestra en las figuras 1 y 2.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="?attr/colorPrimaryContainer"
  android:theme="@style/Theme.Material3.DynamicColors.DayNight">

  <ImageView
    ...
    app:tint="?attr/colorPrimaryContainer"
    android:src="@drawable/ic_partly_cloudy" />

    <!-- Other widget content. -->

</LinearLayout>
Widget en el tema del modo claro
Figura 1. Widget en el tema claro.
Widgets en el tema del modo oscuro
Figura 2: Widget en el tema oscuro

Retrocompatibilidad con colores dinámicos

Los colores dinámicos solo están disponibles en dispositivos que ejecutan Android 12 o versiones posteriores. Para proporcionar un tema personalizado para versiones anteriores, crea un tema predeterminado con tus colores personalizados y un nuevo calificador (values-v31) con los atributos del tema predeterminado.

Este es un ejemplo en el que se usa el tema Material 3:

/values/styles.xml

<resources>
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
    <!-- Override default colorBackground attribute with custom color. -->
    <item name="android:colorBackground">@color/my_background_color</item>

    <!-- Add other colors/attributes. -->

  </style>
</resources>

/values-v31/styles.xml

<resources>
  <!-- Do not override any color attribute. -->
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>

/layout/my_widget_layout.xml

<resources>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:background="?android:attr/colorBackground"
    android:theme="@style/MyWidgetTheme" />
</resources>

Habilita la compatibilidad con voz

Acciones en apps permite que Asistente de Google muestre widgets en respuesta a los comandos por voz relevantes del usuario. Si configuras tu widget para que responda a los intents integrados (BIIs), tu app puede mostrar widgets de forma proactiva en plataformas de Asistente, como Android y Android Auto. Los usuarios tienen la opción de fijar widgets que muestra Asistente en su selector, lo que fomenta la participación en el futuro.

Por ejemplo, puedes configurar el widget de resumen de entrenamiento de tu app de ejercicio para que ejecute los comandos por voz del usuario que activan el BII GET_EXERCISE_OBSERVATION. El Asistente muestra tu widget de forma proactiva cuando los usuarios activan este BII realizando solicitudes como "Hey Google, ¿cuántas millas corrí esta semana en App de Ejemplo?"

Hay docenas de BIIs que abarcan varias categorías de interacción del usuario, lo que permite que casi cualquier app para Android mejore sus widgets para la voz. Para comenzar, consulta Cómo integrar Acciones en apps con widgets de Android.

Cómo mejorar la experiencia con el selector del widget de la app

Android 12 te permite agregar vistas previas y descripciones de widgets escalados. Android 15 te permite mejorar la experiencia del selector de widgets de tu app con vistas previas de widgets generadas.

Para mejorar la experiencia del selector de widgets de tu app, proporciona una vista previa del widget generado en dispositivos Android 15 y versiones posteriores, una vista previa del widget escalado (especificando un previewLayout) para dispositivos Android 12 a Android 14 y un previewImage para versiones anteriores.

Cómo agregar vistas previas de widgets generados al selector de widgets

Las apps deben establecer 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 en dispositivos con Android 15 o versiones posteriores. Esto significa que las apps pueden actualizar el contenido del selector para que sea más representativo de lo que ve el usuario.

Las apps pueden usar los métodos AppWidgetManager, setWidgetPreview y getWidgetPreview para actualizar el aspecto de sus widgets con información actualizada y personalizada.

Genera una vista previa actualizada con Jetpack Glance

Glance.compose ejecuta una composición, por lo que no se usan funciones de suspensión, flujos ni llamadas asíncronas similares en el cuerpo de tu elemento componible. En su lugar, debes usar datos constantes.

En el siguiente ejemplo, se usa Jetpack Glance para generar una vista previa actualizada. Se requiere una configuración de compilación de compileSdk de 35 o una versión 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,
    ExampleAppWidget().compose(
        context = appContext
    ),
)

AppWidgetSnippets.kt

Genera una vista previa actualizada sin Jetpack Glance

Puedes usar RemoteViews sin Glance. En el siguiente ejemplo, se carga un recurso de diseño de widget XML y se establece como la vista previa. Se requiere una 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)
)
AppWidgetSnippets.kt

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. La proporcionas como un diseño XML configurado en el tamaño predeterminado del widget. Anteriormente, la vista previa del widget era un recurso estático de elementos de diseño que, en algunos casos, causaba que las vistas previas no mostraran con exactitud cómo aparecen los widgets cuando se agregan a la pantalla principal.

Para implementar las vistas previas escalables de widgets, usa el atributo previewLayout del elemento appwidget-provider para brindar un diseño XML en su lugar:

<appwidget-provider
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

Recomendamos usar el mismo diseño que el del widget real, con valores realistas predeterminados o de las pruebas. La mayoría de las apps usan los mismos 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 al uso de previewImage si el dispositivo del usuario no admite previewLayout. El atributo previewLayout tiene prioridad sobre el atributo previewImage.

Enfoques recomendados para crear vistas previas precisas

Para implementar las vistas previas escalables de widgets, usa el atributo previewLayout del elemento appwidget-provider para brindar un diseño XML:

<appwidget-provider
    ...
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
Una imagen que muestra una vista previa del widget
Figura 3: Una vista previa del widget que, de forma predeterminada, aparece en un área de 3 × 3, pero puede adaptarse a un área de 3 × 1 debido a su diseño XML.

Para mostrar una vista previa precisa, puedes proporcionar directamente el diseño real del widget con valores predeterminados. Para ello, sigue estos pasos:

  • Configuración de android:text="@string/my_widget_item_fake_1" para elementos TextView

  • Establecer un ícono o una imagen predeterminados o de marcador de posición, como android:src="@drawable/my_widget_icon", para los componentes ImageView

Sin valores predeterminados, es posible que la vista previa muestre valores incorrectos o vacíos. Un beneficio importante de este enfoque es que puedes proporcionar contenido de vista previa localizado.

Si deseas obtener información sobre los enfoques recomendados para vistas previas más complejas que contengan ListView, GridView o StackView, consulta Cómo compilar vistas previas precisas que incluyan elementos dinámicos.

Retrocompatibilidad con vistas previas escalables 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, especifica el atributo previewImage.

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

Agrega un nombre a tu widget

Los widgets deben tener un nombre único cuando se muestran en el selector de widgets.

Los nombres de los widgets se cargan desde el atributo label del elemento receiver del widget en el archivo AndroidManifest.xml.

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

Cómo agregar una descripción para el widget

A partir de Android 12, proporciona una descripción para que el selector del widget se muestre con este.

Una imagen que muestra un selector de widgets con un widget y su descripción
Figura 4: Selector de widgets de muestra que muestra un widget y su descripción.

Proporciona una descripción para el widget con el atributo description del elemento &lt;appwidget-provider&gt;:

<appwidget-provider
    android:description="@string/my_widget_description">
</appwidget-provider>

Puedes usar el atributo descriptionRes en versiones anteriores de Android, pero el selector de widgets lo ignora.

Cómo habilitar transiciones más fluidas

A partir de Android 12, los selectores brindan una transición más fluida cuando un usuario inicia la app desde un widget.

A fin de habilitar la mejora de esta transición, usa @android:id/background o android.R.id.background para identificar el elemento en segundo plano:

// Top-level layout of the widget.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

La app puede usar @android:id/background en versiones anteriores de Android sin errores, pero se ignora.

Cómo utilizar la modificación del tiempo de ejecución de RemoteViews

A partir de Android 12, puedes aprovechar varios métodos RemoteViews que permiten la modificación del tiempo de ejecución de los atributos RemoteViews. Consulta la referencia de la API de RemoteViews para ver la lista completa de métodos agregados.

En el siguiente ejemplo de código, se muestra cómo usar algunos de estos métodos.

Kotlin

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList())

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)

Java

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList());

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);