Cómo compilar un host de widgets

La pantalla principal de Android, disponible en la mayoría de los dispositivos con Android, permite al usuario incorporar widgets de apps (o widgets) para acceder al contenido de forma rápida. Si estás compilando un reemplazo de la pantalla principal o una app similar, también puedes permitir que el usuario incorpore widgets mediante la implementación de AppWidgetHost. Esto no es algo necesario para la mayoría de las apps, pero, si vas a compilar tu propio host, es importante comprender las obligaciones contractuales que un host acepta de manera implícita.

En esta página, se describen las responsabilidades relacionadas con la implementación de un AppWidgetHost personalizado. Para ver un ejemplo específico de cómo implementar un AppWidgetHost, consulta el código fuente de la pantalla principal de Android LauncherAppWidgetHost.

A continuación, se incluye una descripción general de las clases y los conceptos clave relacionados con la implementación de un AppWidgetHost personalizado:

Host de widgets de la app: AppWidgetHost proporciona la interacción con el servicio AppWidget para apps que incorporan widgets en su IU. Un AppWidgetHost debe tener un ID único dentro del propio paquete del host. Este ID sigue siendo persistente en todos los usos del host. Por lo general, el ID es un valor hard-coded que le asigna en su app.
ID de widgets de la app: A cada instancia de widget se le asigna un ID único en el momento de la vinculación. Consulta bindAppWidgetIdIfAllowed() y, para obtener más detalles, la sección Vinculación de widgets que se incluye a continuación. El host obtiene el ID único utilizando allocateAppWidgetId(). Este ID es persistente durante toda la vida útil del widget, es decir, hasta que se quita del host. El paquete de hosting debe conservar cualquier estado específico del host (como el tamaño y la ubicación del widget) y asociarlo con el ID del widget de la app.
Vista del host de widgets de la app: Se puede interpretar AppWidgetHostView como un marco en el que se une el widget cada vez que es necesario que aparezca. Se asigna un widget a un AppWidgetHostView cada vez que el host aumenta el widget.
- De forma predeterminada, el sistema crea un AppWidgetHostView, pero el host puede crear su propia subclase de AppWidgetHostView extendiéndola.
- A partir de Android 12 (nivel de API 31), AppWidgetHostView introduce los los setColorResources() y resetColorResources() métodos para controlar los colores sobrecargados de forma dinámica. El host es responsable de proporcionar los colores a estos métodos.
Paquete de opciones: el AppWidgetHost usa el paquete de opciones para enviar información al AppWidgetProvider sobre cómo se muestra el widget (por ejemplo, la lista de rangos de tamaños) y si el widget está en una pantalla de bloqueo o en la pantalla principal. Esta información permite que el AppWidgetProvider adapte el contenido y la apariencia del widget en función de cómo y dónde se muestra. Puedes usar updateAppWidgetOptions() y updateAppWidgetSize() para modificar el paquete de widgets. Ambos métodos activan la onAppWidgetOptionsChanged() devolución de llamada a AppWidgetProvider.

Vinculación de widgets

Cuando un usuario agrega un widget a un host, se produce un proceso llamado vinculación. La vinculación consiste en asociar un ID de un widget de la app en particular a un host y a un específico AppWidgetProvider.

Las APIs de vinculación también permiten que un host proporcione una IU personalizada para la vinculación. Para usar este proceso, tu app debe declarar el BIND_APPWIDGET permiso en el manifiesto del host:

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

Pero este es solo el primer paso. Durante el tiempo de ejecución, el usuario debe otorgar de manera explícita permiso a tu app para que pueda agregar un widget al host. Si quieres probar si tu app tiene permiso para agregar el widget, usa el bindAppWidgetIdIfAllowed() método. Si bindAppWidgetIdIfAllowed() muestra false, tu app debe mostrar un cuadro de diálogo en el que se le pide al usuario que otorgue permiso: "permitir" para la adición del widget actual o "permitir siempre" para cubrir todas las adiciones de widgets futuras.

En este fragmento, se proporciona un ejemplo de cómo mostrar el diálogo:

Kotlin

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)

Java

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle described in the preceding section.
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

El host debe verificar si el widget que agrega un usuario necesita configuración. Para obtener más información, consulta Cómo permitir que los usuarios configuren widgets de apps.

Responsabilidades del host

Puedes especificar una serie de parámetros de configuración para los widgets mediante los AppWidgetProviderInfo metadatos. Puedes recuperar estas opciones de configuración, que se analizan con más detalle en las siguientes secciones, desde el AppWidgetProviderInfo objeto asociado con un proveedor de widgets.

Sin importar la versión de Android a la que se oriente tu app, todos los hosts tienen las siguientes responsabilidades:

Cuando agregues un widget, asigna el ID de este como se describió anteriormente. Cuando se quita un widget del host, llama a deleteAppWidgetId() para anular la asignación del ID del widget.
Cuando agregues un widget, verifica si se debe iniciar la actividad de configuración. Por lo general, el host debe iniciar la actividad de configuración del widget si existe y no está marcada como opcional especificando las marcas configuration_optional y reconfigurable. Consulta Cómo actualizar el widget desde la actividad de configuración para obtener más información. Este paso es necesario para que muchos widgets se muestren.

Nota: Controla los casos irregulares en los que la actividad de configuración no regresa o finaliza con errores.
Los widgets especifican un ancho y una altura predeterminados en los AppWidgetProviderInfo metadatos. Estos valores se definen en celdas (a partir de Android 12, si se especifican targetCellWidth y targetCellHeight) o en dps si solo se especifican minWidth y minHeight. Consulta Atributos de tamaño de widgets.

Asegúrate de que el widget esté diseñado con al menos esta cantidad de dps. Por ejemplo, muchos hosts alinean íconos y widgets en una cuadrícula. En este caso, de forma predeterminada, el host agrega el widget con la cantidad mínima de celdas que cumplan con las restricciones minWidth y minHeight.

Además de los requisitos enumerados en la sección anterior, las versiones específicas de la plataforma introducen funciones que otorgan nuevas responsabilidades al host.

Determina tu enfoque según la versión de Android de destino

Android 12

Android 12 (nivel de API 31) incluye un List<SizeF> adicional que contiene la lista de tamaños posibles en dps que puede tomar una instancia de widget en el paquete de opciones. La cantidad de tamaños proporcionados depende de la implementación del host. Por lo general, los hosts proporcionan dos tamaños para teléfonos (vertical y horizontal) y cuatro tamaños para dispositivos plegables.

Existe un límite de MAX_INIT_VIEW_COUNT (16) en la cantidad de RemoteViews diferentes que un AppWidgetProvider puede proporcionar a RemoteViews. Dado que los objetos AppWidgetProvider asignan un objeto RemoteViews a cada tamaño de List<SizeF>, no proporciones más de MAX_INIT_VIEW_COUNT tamaños.

Android 12 también introduce los maxResizeWidth y maxResizeHeight atributos en dps. Te recomendamos que un widget que use al menos uno de estos atributos no supere el tamaño especificado por los atributos.

Recursos adicionales

Consulta la Glance documentación de referencia.