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 mejorar las suscripciones experiencia del widget.

Usa 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 brinda una experiencia las transiciones y la coherencia entre distintos widgets.

Hay dos maneras de lograr colores dinámicos:

• Usar el tema predeterminado del sistema (@android:style/Theme.DeviceDefault.DayNight) en el diseño raíz.

• Usa el tema de Material 3 (Theme.Material3.DynamicColors.DayNight) de la Componentes de Material para En Android disponible a partir de la página Componentes de Material para Android Versión 1.6.0

Una vez que el tema esté configurado en el diseño raíz, podrás usar atributos de color comunes en la raíz o cualquiera de sus elementos secundarios para recoger los colores dinámicos.

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

• ?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 la luz y a la oscuridad. como los que se muestran 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>

Retrocompatibilidad con colores dinámicos

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

A continuación, se muestra un ejemplo con el tema de Material 3:

<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>

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

<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 mostrar widgets en respuesta a los comandos por voz relevantes del usuario. Si configuras tu para responder a los intents integrados (BIIs), el La app puede mostrar de forma proactiva widgets en plataformas de Asistente, como Android y Android Auto Los usuarios tienen la opción de fijar widgets que muestra Asistente a su para fomentar la participación en el futuro.

Por ejemplo, puedes configurar el widget de resumen de entrenamiento para tu app de ejercicio para cumplir con los comandos por voz del usuario que activan la GET_EXERCISE_OBSERVATION BII. Asistente muestra tu widget de forma proactiva cuando los usuarios activan este BII de la siguiente manera: haciendo 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 permitió que casi cualquier app de Android mejorara sus widgets para usar 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 mejorar la experiencia con el selector del widget para tu 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 se muestra en el selector de widgets es escalable. Lo proporcionas como un diseño XML configurado en el el tamaño predeterminado. Anteriormente, la vista previa del widget era un recurso de elemento de diseño estático, en algunos casos, lo que lleva a vistas previas que reflejan incorrectamente cómo aparecen los widgets cuando se agregan a la pantalla de inicio.

Para implementar vistas previas escalables de widgets, usa el previewLayout del elemento appwidget-provider para proporcionar 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 widget real, con valores predeterminados realistas o valores de prueba. La mayoría de las apps usan los mismos previewLayout y initialLayout. Para guía para crear diseños de vista previa precisos, consulta la siguiente sección .

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 crear vistas previas precisas

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

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

Para mostrar una vista previa precisa, puedes proporcionar directamente el widget real con valores predeterminados completando los siguientes pasos:

• Configurando android:text="@string/my_widget_item_fake_1" para TextView o de terceros.

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

Si no hay valores predeterminados, es posible que la vista previa muestre valores incorrectos o vacíos. Los La ventaja importante de este enfoque es que puedes ofrecer una vista previa localizada contenido.

En el caso de los enfoques recomendados para vistas previas más complejas que contienen ListView, haz lo siguiente: GridView o StackView, consulta Cómo crear vistas previas precisas que incluyan anuncios dinámicos artículos para conocer más detalles.

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 tus widget, especifica el elemento 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 del widget selector para mostrar en tu widget.

Proporciona una descripción para tu widget con el atributo description del Elemento <appwidget-provider>:

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

Puedes usar la descriptionRes en versiones anteriores de Android, pero el widget lo ignora selector.

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 romperse, pero se ignora.

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

A partir de Android 12, puedes aprovechar varias Métodos RemoteViews que permiten modificar el tiempo de ejecución de RemoteViews atributos. Consulta 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.

// 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)

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