Cómo crear un widget simple

Prueba hacerlo con Compose
Jetpack Compose es el kit de herramientas de IU recomendado para Android. Aprende a compilar widgets con APIs de estilo Compose.
Jetpack Glance →

Los widgets son vistas de apps en miniatura que puedes incorporar en otras apps, como la pantalla principal, y recibir actualizaciones periódicas. Estas vistas se denominan widgets en la interfaz de usuario, y puedes publicar una con un proveedor de widgets de apps (o proveedor de widgets). Un componente de la app que contiene otros widgets se denomina host de widgets de la app (o host de widgets). En la figura 1, se muestra un ejemplo de widget de música:

Ejemplo de widget de música
Figura 1: Ejemplo de un widget de música.

En este documento, se describe cómo publicar un widget con un proveedor de widgets. Para obtener detalles sobre cómo crear tu propio AppWidgetHost para alojar widgets de apps, consulta Cómo compilar un host de widgets.

Para obtener información sobre cómo diseñar tu widget, consulta Descripción general de los widgets de apps.

Componentes de widgets

Para crear un widget, necesitas los siguientes componentes básicos:

Objeto AppWidgetProviderInfo
Describe los metadatos de un widget, como el diseño, la frecuencia de actualización y la clase AppWidgetProvider. AppWidgetProviderInfo se define en XML, como se describe en este documento.
Clase AppWidgetProvider
Define los métodos básicos que te permiten interactuar de manera programática con el widget. De esta manera, recibirás emisiones cuando se actualice, se habilite, se inhabilite o se borre el widget. Declara AppWidgetProvider en el manifiesto y, luego, implementa el servicio, como se describe en este documento.
Diseño de la vista
Define el diseño inicial del widget. El diseño se define en XML, como se describe en este documento.

En la figura 2, se muestra cómo estos componentes se ajustan al flujo general de procesamiento de widgets de la app.

Flujo de procesamiento del widget de la app
Figura 2: Flujo de procesamiento del widget de la app.

Si tu widget necesita configuración del usuario, implementa la actividad de configuración del widget de la app. Esta actividad permite a los usuarios modificar la configuración de los widgets, por ejemplo, la zona horaria de un widget de reloj.

También recomendamos las siguientes mejoras: diseños de widgets flexibles, mejoras varias, widgets avanzados, widgets de colección y cómo compilar un host de widgets.

Declara el XML de AppWidgetProviderInfo

La definición de la configuración de metadatos (como los tamaños de celda predeterminados, las restricciones de cambio de tamaño y las frecuencias de actualización) es exactamente igual en las vistas tradicionales y en los widgets basados en Glance.

Para obtener información sobre cómo definir y configurar tu archivo en formato XML de metadatos, consulta la sección Declarar el archivo XML de AppWidgetProviderInfo de la documentación de Glance.

Usa la clase AppWidgetProvider para controlar las transmisiones de widgets

Los mecanismos del receptor de transmisiones, los filtros de declaración del manifiesto y los bucles de eventos de ciclo de vida de la plataforma están unificados en la plataforma. En el desarrollo de Compose primero, estas transmisiones se organizan con el wrapper GlanceAppWidgetReceiver.

Para comprender cómo registrar tu receptor en el manifiesto y cómo implementar anulaciones del ciclo de vida compatibles con Hilt, consulta la sección Usa la clase AppWidgetProvider para controlar emisiones en la documentación de Glance.

Crea el diseño del widget

Debes definir un diseño inicial para el widget en formato XML y guardarlo en el directorio res/layout/ del proyecto. Consulta los Lineamientos de diseño para obtener más detalles.

Crear el diseño del widget es sencillo si tienes conocimientos sobre los diseños. Sin embargo, ten en cuenta que los diseños de los widgets se basan en RemoteViews, que no admite todo tipo de diseño o widget de vista. No puedes usar vistas personalizadas ni subclases de las vistas que admite RemoteViews.

RemoteViews también admite ViewStub, que es un View invisible de tamaño cero que puedes usar para aumentar de forma diferida los recursos de diseño durante el tiempo de ejecución.

Compatibilidad para comportamientos con estado

Android 12 agrega compatibilidad para comportamientos con estados a través de los siguientes componentes existentes:

El widget todavía no tiene un estado. La app debe almacenar el estado y registrarse para los eventos de cambio de estado.

Ejemplo de un widget de lista de compras que muestra un comportamiento con estado
Figura 3: Ejemplo de comportamiento con estado.

En el siguiente ejemplo de código, se muestra cómo implementar estos componentes.

Kotlin

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
        R.id.my_checkbox,
        RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)

Java

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));

Proporciona dos diseños: uno que se oriente a dispositivos que ejecutan Android 12 o versiones posteriores en res/layout-v31, y el otro que se oriente a versiones anteriores de Android 11 o versiones anteriores en la carpeta res/layout predeterminada.

Cómo implementar esquinas redondeadas

El cálculo de los radios externos y proporcionales internos es estándar y compartido. En el desarrollo que prioriza Compose, esto se puede configurar de forma dinámica en Kotlin junto con los recursos de temas personalizados.

Para implementar radios de esquinas o configurar estilos dinámicos para dispositivos Android más antiguos, consulta la sección Implementar esquinas redondeadas centrada en Compose en la documentación de Glance.