Cómo compilar un host de widgets

La pantalla principal de Android, disponible en la mayoría de los dispositivos con Android, permite que el usuario incorpore widgets de apps (o widgets) para acceder rápidamente al contenido. Si estás creando un reemplazo de la pantalla principal o una app similar, también puedes permitir que el usuario incorpore widgets implementando AppWidgetHost. Esto no es algo que la mayoría de las apps deban hacer, pero si creas tu propio host, es importante que comprendas las obligaciones contractuales que un host acepta de forma implícita.

En esta página, se describen las responsabilidades que implica implementar 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 que se incluyen en la implementación de un AppWidgetHost personalizado:

• Host del widget de la app: AppWidgetHost proporciona la interacción con el servicio de AppWidget para las apps que incorporan widgets en su IU. Un AppWidgetHost debe tener un ID que sea único dentro del paquete del host. Este ID persiste en todos los usos del host. Por lo general, el ID es un valor codificado que asignas en tu app.

• ID del widget de la app: A cada instancia del 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 Vincula widgets que aparece a continuación. El host obtiene el ID único con allocateAppWidgetId(). Este ID persiste durante el ciclo de vida del widget hasta que se borra 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 del widget de la app: Piensa en AppWidgetHostView como un marco en el que se une el widget cada vez que se debe mostrar. Un widget se asocia con 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éndolo.
  • A partir de Android 12 (nivel de API 31), AppWidgetHostView presenta los métodos setColorResources() y resetColorResources() 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 comunicar información al AppWidgetProvider sobre cómo se muestra el widget, por ejemplo, la lista de rangos de tamaño, y si el widget está en una pantalla de bloqueo o en la pantalla principal. Esta información permite que AppWidgetProvider adapte el contenido y la apariencia del widget según cómo y dónde se muestra. Puedes usar updateAppWidgetOptions() y updateAppWidgetSize() para modificar el paquete de un widget. Ambos métodos activan la devolución de llamada onAppWidgetOptionsChanged() 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 se refiere a asociar un ID de widget de app en particular con un host específico y un AppWidgetProvider específico.

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 permiso BIND_APPWIDGET en el manifiesto del host:

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

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

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

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

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 la app.

Responsabilidades del organizador

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

Todos los anfitriones tienen las siguientes responsabilidades:

• Cuando agregues un widget, asigna el ID del widget como se describió anteriormente. Cuando se quita un widget del host, llama a deleteAppWidgetId() para desasignar el ID del widget.

• Cuando agregues un widget, verifica si es necesario 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 Actualiza el widget desde la actividad de configuración para obtener más detalles. Este es un paso necesario para muchos widgets antes de que se puedan mostrar.

  Nota: Controla los casos irregulares en los que la actividad de configuración no se devuelve o finaliza con errores.

• Los widgets especifican un ancho y una altura predeterminados en los metadatos de AppWidgetProviderInfo. 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 se diseñe con, al menos, esta cantidad de dp. Por ejemplo, muchos hosts alinean íconos y widgets en una cuadrícula. En esta situación, de forma predeterminada, el host agrega un widget con la cantidad mínima de celdas que satisfacen las restricciones minWidth y minHeight.

Sugerencias para tu enfoque

Además de los requisitos que se indican en la sección anterior, ten en cuenta las siguientes sugerencias:

El paquete de opciones puede contener un List<SizeF> que incluya la lista de tamaños posibles en dp que puede adoptar una instancia de widget. 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 en List<SizeF>, no proporciones más de MAX_INIT_VIEW_COUNT tamaños.

Cuando los widgets especifican los atributos maxResizeWidth y maxResizeHeight en dps, 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 documentación de referencia de Glance.