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 puedes implementar y mejorar fácilmente la experiencia del widget de tus usuarios.

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. De esta manera, se proporcionan transiciones más fluidas y coherencia en diferentes widgets.

Existen dos maneras de lograr colores dinámicos:

Una vez que el tema esté establecido en el diseño raíz, podrás usar atributos de color comunes en la raíz o en cualquiera de sus elementos secundarios para seleccionar 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, con el tema de 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 con Tema claro
Widgets en el tema del modo oscuro
Figura 2: Widget con tema oscuro

Retrocompatibilidad con colores dinámicos

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

En este ejemplo, se usa el tema de 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>

Habilitar la compatibilidad por voz

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

Por ejemplo, puedes configurar el widget de resumen de entrenamiento de tu app de ejercicio para entregar los comandos por voz del usuario que activan el BII GET_EXERCISE_OBSERVATION. Asistente muestra tu widget de forma proactiva cuando los usuarios activan este BII mediante solicitudes como "Hey Google, ¿cuántos kilómetros corrí esta semana en AppDeEjemplo?".

Hay decenas de BIIs que abarcan varias categorías de interacción del usuario, lo que permite que casi cualquier app para Android mejore sus widgets de 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 mejorar la experiencia del selector del widget para tu app agregando vistas previas dinámicas y descripciones de widgets.

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 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, generaba vistas previas que mostraban de forma imprecisa cómo se mostraban los widgets cuando 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 widget real, con valores predeterminados o de prueba realistas. La mayoría de las apps usan el mismo previewLayout y initialLayout. Para obtener ayuda sobre cómo crear diseños de vista previa precisos, consulta la siguiente sección de esta página.

Recomendamos especificar los atributos previewLayout y previewImage, para que tu app pueda volver a usar previewImage si el dispositivo del usuario no es compatible con previewLayout. El atributo previewLayout tiene prioridad sobre el atributo previewImage.

Enfoques recomendados para compilar vistas previas precisas

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

<appwidget-provider
    ...
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
Una imagen que muestra una vista previa de un widget
Figura 3: Vista previa de un widget que, de forma predeterminada, aparece en un área de 3 x 3, pero puede caber en un área de 3 x 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 completando los siguientes pasos:

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

  • Configuración de una imagen o un ícono predeterminados o de marcador de posición, como android:src="@drawable/my_widget_icon", para componentes de 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 conocer los enfoques recomendados para las vistas previas más complejas que contienen ListView, GridView o StackView, consulta Cómo compilar vistas previas precisas que incluyan elementos dinámicos para obtener más información.

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 la apariencia del widget, actualiza la imagen de vista previa.

Cómo agregar una descripción para el widget

A partir de Android 12, proporciona una descripción para que el selector de widgets muestre tu widget.

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

Brinda una descripción para tu 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>

Tu app puede usar @android:id/background en versiones anteriores de Android sin problemas, pero se ignorará.

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 proporcionan 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);