La pantalla principal de Android, disponible en la mayoría de los dispositivos con Android, le permite al usuario incorporar widgets de apps (o widgets) para un acceso rápido al contenido. 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 creas tu propio host, es importante comprender las obligaciones contractuales que un host acepta implícitamente.
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 las apps que incorporan widgets en su IU. UnAppWidgetHost
debe tener un ID único dentro del propio 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 información, la sección Widgets de vinculación a continuación. El host obtiene el ID único medianteallocateAppWidgetId()
. Este ID persiste durante toda la vida útil 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 al que se une el widget cada vez que debe mostrarse. Un widget se asocia con unAppWidgetHostView
cada vez que el host aumenta el widget.- De forma predeterminada, el sistema crea un
AppWidgetHostView
, pero el host puede crear su propia subclase deAppWidgetHostView
extendiéndola. - A partir de Android 12 (nivel de API 31),
AppWidgetHostView
presenta los métodossetColorResources()
yresetColorResources()
para controlar los colores sobrecargados de forma dinámica. El host es responsable de proporcionar los colores a estos métodos.
- De forma predeterminada, el sistema crea un
Paquete de opciones:
AppWidgetHost
usa el paquete de opciones para comunicar información aAppWidgetProvider
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 queAppWidgetProvider
adapte el contenido y la apariencia del widget en función de cómo y dónde se muestra. Puedes usarupdateAppWidgetOptions()
yupdateAppWidgetSize()
para modificar el paquete de un widget. Ambos métodos activan la devolución de llamadaonAppWidgetOptionsChanged()
aAppWidgetProvider
.
Widgets de vinculación
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 un widget de la app en particular con un host y un AppWidgetProvider
específicos.
Las APIs de vinculación también permiten que un host proporcione una IU personalizada para la vinculación. Para usar este proceso, la 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. Durante el tiempo de ejecución, el usuario debe otorgar de manera explícita permiso a tu app para permitirle agregar un widget al host. Si quieres 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 permiso: "permitir" para la adición actual del widget o "permitir siempre" para abarcar todas las incorporaciones futuras de widgets.
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. Si deseas obtener más información, consulta Permite que los usuarios configuren los widgets de la app.
Responsabilidades del host
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 explican con más detalle en las siguientes secciones, desde el objeto AppWidgetProviderInfo
asociado con un proveedor de widgets.
Independientemente de la versión de Android de destino, todos los hosts tienen las siguientes responsabilidades:
Cuando agregues un widget, asigna el ID del widget como se describió anteriormente. Cuando se quite 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. Para ello, especifica las marcas
configuration_optional
yreconfigurable
. Para obtener más detalles, consulta Cómo actualizar el widget desde la actividad de configuración. Este es un paso necesario para que muchos widgets puedan mostrarse.Los widgets especifican un ancho y una altura predeterminados en los metadatos
AppWidgetProviderInfo
. Estos valores se definen en celdas (a partir de Android 12, si se especificantargetCellWidth
ytargetCellHeight
) o en dps si solo se especificanminWidth
yminHeight
. Consulta Atributos de tamaño de widgets.Asegúrate de que el widget esté dispuesto con al menos esta cantidad de dp. Por ejemplo, muchos hosts alinean los íconos y widgets en una cuadrícula. En este caso, de forma predeterminada, el host agrega un widget con la cantidad mínima de celdas que cumplen con las restricciones
minWidth
yminHeight
.
Además de los requisitos enumerados en la sección anterior, las versiones de plataforma específicas presentan funciones que otorgan nuevas responsabilidades al host.
Determina tu enfoque en función de la versión de Android de destino
Android 12
Android 12 (nivel de API 31) empaqueta un List<SizeF>
adicional que contiene la lista de posibles tamaños en dps que una instancia de widget puede tomar en el paquete de opciones.
La cantidad de tamaños proporcionados depende de la implementación del host. Por lo general, los hosts ofrecen 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.
Android 12 también introduce 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
.