Los widgets de apps son vistas en miniatura de una app 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 uno con un proveedor de widgets de apps (o proveedor de widgets). Un componente de la app que contiene otros widgets se denomina host de widget de la app (o host de widget). En la Figura 1, se muestra un widget de música de ejemplo:
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 la app.
Componentes de widgets
Para crear un widget, necesitas los siguientes componentes básicos:
- Objeto
AppWidgetProviderInfo - Describe los metadatos de un widget, como su diseño, la frecuencia de actualización y la clase
AppWidgetProvider.AppWidgetProviderInfose 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. A través de él,
recibes transmisiones cuando se actualiza, habilita, inhabilita o
borra el widget. Declaras
AppWidgetProvideren el manifiesto y, luego, lo implementas, 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.
Si tu widget necesita configuración del usuario, implementa la actividad de configuración del widget de la app. Esta actividad permite que los usuarios modifiquen la configuración del widget, por ejemplo, la zona horaria de un widget de reloj.
- A partir de Android 12 (nivel de API 31), puedes proporcionar una configuración predeterminada y permitir que los usuarios vuelvan a configurar el widget más adelante. Consulta Usa la configuración predeterminada del widget y Permite que los usuarios vuelvan a configurar los widgets colocados para obtener más detalles.
- En Android 11 (nivel de API 30) o versiones anteriores, esta actividad se inicia cada vez que el usuario agrega el widget a su pantalla principal.
También te recomendamos las siguientes mejoras: diseños de widgets flexibles, mejoras varias, widgets avanzados, widgets de colección y compilación de 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 idéntica en las vistas tradicionales y en los widgets basados en Glance.
Para aprender a definir y configurar tu archivo en formato XML de metadatos, consulta la sección Declara el XML de AppWidgetProviderInfo de Compose-first en 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 del ciclo de vida de la plataforma se unifican debajo de ella. En el desarrollo que prioriza Compose, estas transmisiones se organizan con el wrapper GlanceAppWidgetReceiver.
Para comprender cómo registrar tu receptor en el manifiesto y, además, implementar anulaciones del ciclo de vida compatibles con Hilt, consulta la sección Usa la clase AppWidgetProvider para controlar transmisiones de la documentación de Glance, que se enfoca en Compose.
Crea el diseño del widget
Debes definir un diseño inicial para tu widget en 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 conoces los diseños. Sin embargo, ten en cuenta que los diseños de widgets se basan en RemoteViews, que no admite todos los tipos de diseño ni widgets de vista.
No puedes usar vistas personalizadas ni subclases de las vistas que admite RemoteViews.
RemoteViews también admite ViewStub, que es un objeto 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 con el comportamiento con estado
Android 12 agrega compatibilidad con el comportamiento con estado 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.
En el siguiente ejemplo de código, se muestra cómo implementar estos componentes.
// 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 orientado a dispositivos que ejecutan Android 12 o versiones posteriores en res/layout-v31 y otro orientado a versiones anteriores de Android 11 o anteriores en la carpeta predeterminada res/layout.
Cómo implementar esquinas redondeadas
El cálculo de los radios proporcionales internos y externos del fondo 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 esquina o configurar estilos dinámicos para dispositivos Android más antiguos, consulta la sección Implementa esquinas redondeadas de Compose en la documentación de Glance.