Cómo compilar un host de widgets

La pantalla de inicio de Android, disponible en la mayoría de los dispositivos con Android, permite que el el usuario puede incorporar widgets de aplicaciones (o widgets) para acceso rápido al contenido. Si estás compilando un reemplazo de la pantalla principal app similar, también puedes permitir que el usuario incorpore widgets implementando AppWidgetHost No es es algo que la mayoría de las apps deben hacer, pero si creas tu propio host, es importante comprender las obligaciones contractuales que un host acepta implícitamente.

Esta página se enfoca en las responsabilidades involucradas en la implementación de un programa AppWidgetHost Para ver un ejemplo específico de cómo implementar un AppWidgetHost, observa el código fuente de la pantalla principal de Android LauncherAppWidgetHost

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

  • Host del widget de la app: el AppWidgetHost proporciona la interacción con el Servicio AppWidget para apps que incorporan widgets en su IU. Un AppWidgetHost debe tener un ID que sea único dentro del paquete del host. Este ID persiste para todos los usos del host. El ID suele ser un valor codificado que puedes asignar en tu app.

  • ID del widget de la app: A cada instancia de widget se le asigna un ID único en ese momento. de vinculación. Consulta bindAppWidgetIdIfAllowed() Para obtener más información, consulta la sección Vinculación de widgets a continuación. El host obtiene el ID único mediante allocateAppWidgetId() Este ID persiste durante todo el ciclo de vida del widget hasta que se borra del host. Cualquier estado específico del host, como el tamaño y la ubicación del widget) debe conservarse en el paquete de hosting y asociarse con el ID del widget de la app.

  • Vista del host del widget de la app: piensa en AppWidgetHostView como marco que se unirá el widget cada vez que deba mostrarse. Un widget es se asocia con un AppWidgetHostView cada vez que el widget aumenta el widget host.

    • De forma predeterminada, el sistema crea un AppWidgetHostView, pero el host puede Extiende tu propia subclase de AppWidgetHostView.
    • A partir de Android 12 (nivel de API 31), AppWidgetHostView presenta la el setColorResources() y resetColorResources() para manejar colores sobrecargados de forma dinámica. El anfitrión es responsable de proporcionar los colores a estos métodos.

  • Paquete de opciones: AppWidgetHost usa el paquete de opciones para comunicar información al AppWidgetProvider sobre cómo se muestra el widget, por ejemplo, el lista de rangos de tamaño, y si el está en una pantalla de bloqueo o en la pantalla principal. Esta información le permite al AppWidgetProvider adapta el contenido y la apariencia del widget en función de cómo y donde aparecen. Puedes usar updateAppWidgetOptions() y updateAppWidgetSize() para modificar el paquete de un widget. Ambos métodos activan el onAppWidgetOptionsChanged() a AppWidgetProvider.

Cómo vincular widgets

Cuando un usuario agrega un widget a un host, se produce un proceso llamado vinculación. Vinculación se refiere a la asociación de un ID de widget de la app específico con un host específico y un AppWidgetProvider específico.

Las APIs de vinculació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. En el tiempo de ejecución, el usuario debe otorgar explícitamente permiso a tu app para que pueda agregar un widget al host. Para probar si tu app tiene permiso para agregar el widget, usa el bindAppWidgetIdIfAllowed() . Si bindAppWidgetIdIfAllowed() muestra false, tu app debe mostrar un Diálogo que le solicita al usuario que otorgue el permiso: "allow" del widget actual adición o "permitir siempre" para cubrir todas las adiciones 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. Para Para obtener más información, consulta Cómo permitir que los usuarios configuren la app widgets.

Responsabilidades del host

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

Sin importar la versión de Android a la que te orientes, todos los hosts tienen la las siguientes responsabilidades:

  • Cuando agregues un widget, asigna su ID como se describió anteriormente. Cuando un elemento widget se quita del host, llama deleteAppWidgetId() para anular la asignación del ID del widget.

  • Cuando agregues un widget, comprueba si se debe lanzamiento. Por lo general, el host debe iniciar la configuración del widget si existe y no está marcada como opcional especificando los dos Las marcas configuration_optional y reconfigurable. Consulta Actualiza el widget desde la actividad de configuración para conocer los detalles. Este es un paso necesario para que muchos widgets puedan mostrarse.

  • Los widgets especifican un ancho y una altura predeterminados en AppWidgetProviderInfo. metadatos. Estos valores se definen en celdas, a partir de Android 12, si targetCellWidth y targetCellHeight son o dps si solo se especifican minWidth y minHeight. Consulta Atributos de tamaño de widgets.

    Asegúrate de que el widget esté dispuesto con al menos esta cantidad de dps. Para Por ejemplo, muchos hosts alinean íconos y widgets en una cuadrícula. En este escenario, al de forma predeterminada, el host agrega un widget utilizando el número mínimo de celdas que satisface las restricciones minWidth y minHeight.

Además de los requisitos enumerados en la sección anterior, de la plataforma introducen funciones que asignan 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 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 organizadores 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) para la cantidad de RemoteViews que un AppWidgetProvider puede proporcionar a RemoteViews Dado que los objetos AppWidgetProvider asignan un objeto RemoteViews a cada tamaño en el List<SizeF>, no proporciones más de MAX_INIT_VIEW_COUNT tamaños.

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

Recursos adicionales

  • Consulta la documentación de referencia de Glance.