Cómo crear un widget de la app con Glance

manifiesto, metadatos

En las siguientes secciones, se describe cómo crear un widget básico de la app con Glance.

Cómo declarar AppWidget en el manifiesto

Después de completar los pasos de configuración, declara AppWidget y sus metadatos en tu app.

1. Extiende el receptor AppWidget desde GlanceAppWidgetReceiver:

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
       override val glanceAppWidget: GlanceAppWidget = TODO("Create GlanceAppWidget")
   }
   GlanceSnippets.kt

2. Registra el proveedor del widget de la app en tu archivo AndroidManifest.xml y en el archivo de metadatos asociado:

       <receiver android:name=".glance.MyReceiver"
       android:exported="true">
       <intent-filter>
           <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
       </intent-filter>
       <meta-data
           android:name="android.appwidget.provider"
           android:resource="@xml/my_app_widget_info" />
   </receiver>
   AndroidManifest.xml
   

Agrega los metadatos de AppWidgetProviderInfo

A continuación, sigue la guía Crea un widget para crear y definir la información del widget de la app en el archivo @xml/my_app_widget_info.

La única diferencia para Glance es que no hay un XML de initialLayout, pero debes definir uno. Puedes usar el diseño de carga predefinido que se proporciona en la biblioteca:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:initialLayout="@layout/glance_default_loading_layout">
</appwidget-provider>
my_app_widget_info.xml

Declara el XML de AppWidgetProviderInfo

El objeto AppWidgetProviderInfo define las cualidades esenciales de tu widget. Define AppWidgetProviderInfo en tu archivo de recursos de metadatos XML (res/xml/my_app_widget_info.xml) dentro de un elemento <appwidget-provider>:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/glance_default_loading_layout"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

Atributos de tamaño del widget

En la pantalla principal predeterminada, se colocan los widgets en la ventana según una cuadrícula de celdas que tienen una altura y un ancho definidos. La mayoría de las pantallas principales solo permiten que los widgets adopten tamaños que sean múltiplos enteros de las celdas de la cuadrícula, por ejemplo, dos celdas horizontales por tres celdas verticales.

Los atributos de tamaño del widget te permiten especificar un tamaño predeterminado para tu widget y proporcionar límites inferior y superior para el tamaño del widget. En este contexto, el tamaño predeterminado de un widget es el tamaño que adopta el widget cuando se agrega por primera vez a la pantalla principal.

En la siguiente tabla, se describen los atributos de <appwidget-provider> relacionados con el tamaño del widget:

Ejemplo

Para ilustrar cómo los atributos de la tabla anterior afectan el tamaño del widget, supón las siguientes especificaciones:

• Una celda de la cuadrícula tiene 30 dp de ancho y 50 dp de alto.
• Se proporciona la siguiente especificación de atributos:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

A partir de Android 12:

Usa los atributos targetCellWidth y targetCellHeight como el tamaño predeterminado del widget.

El tamaño predeterminado del widget es de 2 x 2. El widget se puede reducir hasta 2x1 o aumentar hasta 4x3.

Android 11 y versiones anteriores:

Usa los atributos minWidth y minHeight para calcular el tamaño predeterminado del widget.

El ancho predeterminado = Math.ceil(80 / 30) = 3

La altura predeterminada = Math.ceil(80 / 50) = 2

El tamaño predeterminado del widget es de 3 x 2. El widget se puede reducir a 2 x 1 o expandir a pantalla completa.

Atributos adicionales del widget

En la siguiente tabla, se describen los atributos de <appwidget-provider> relacionados con cualidades que no son el tamaño del widget.

Define GlanceAppWidget

1. Crea una clase nueva que extienda GlanceAppWidget y anule el método provideGlance. Este es el método en el que puedes cargar los datos necesarios para renderizar tu widget:

   class MyAppWidget : GlanceAppWidget() {
   
       override suspend fun provideGlance(context: Context, id: GlanceId) {
   
           // In this method, load data needed to render the AppWidget.
           // Use `withContext` to switch to another thread for long running
           // operations.
   
           provideContent {
               // create your AppWidget here
               Text("Hello World")
           }
       }
   }
   GlanceSnippets.kt

2. Crea una instancia en el glanceAppWidget de tu GlanceAppWidgetReceiver:

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
   
       // Let MyAppWidgetReceiver know which GlanceAppWidget to use
       override val glanceAppWidget: GlanceAppWidget = MyAppWidget()
   }
   GlanceSnippets.kt

Ya configuraste un AppWidget con Glance.

Usa la clase AppWidgetProvider para controlar las transmisiones de widgets

El widget de coordenadas GlanceAppWidgetReceiver transmite y actualiza el estado de la plataforma extendiendo el AppWidgetProvider subyacente. Recibe eventos de la plataforma cuando se actualiza, borra, habilita o inhabilita tu widget, y los traduce en solicitudes de ciclo de vida de Compose.

Cómo declarar un widget en el manifiesto

Declara tu subclase de la clase GlanceAppWidgetReceiver como un receptor de transmisiones en tu archivo AndroidManifest.xml:

<receiver android:name="ExampleAppWidgetReceiver"
          android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/my_app_widget_info" />
</receiver>

El elemento <receiver> requiere el atributo android:name, que especifica la clase del receptor. El receptor debe aceptar la acción de emisión ACTION_APPWIDGET_UPDATE dentro de <intent-filter>.

El elemento <meta-data> debe identificar su nombre como android.appwidget.provider, y el atributo android:resource debe apuntar a tu recurso de metadatos XML de AppWidgetProviderInfo (@xml/my_app_widget_info).

Implementa la clase AppWidgetProvider

En Glance, extiendes GlanceAppWidgetReceiver en lugar de AppWidgetProvider directamente. Para implementarlo, vincula tu receptor a tu instancia de GlanceAppWidget. Las devoluciones de llamada principales disponibles en GlanceAppWidgetReceiver funcionan de la siguiente manera:

• onUpdate(): Glance la anula automáticamente para ejecutar actualizaciones de composición. Si anulas onUpdate de forma manual, debes llamar a super.onUpdate para permitir que Glance inicie correctamente los subprocesos de composición.
• onAppWidgetOptionsChanged(): Se llama a este método cuando se coloca o cambia el tamaño del widget por primera vez. Las opciones de lectura rápida agrupan elementos de forma interna para que tu diseño se ajuste sin problemas según las dimensiones del tiempo de ejecución.
• onDeleted(Context, IntArray): Se invoca cada vez que el usuario borra una instancia de widget específica.
• onEnabled(Context): Se activa cuando se crea correctamente la primera instancia de tu widget. Es excelente para ejecutar migraciones globales.
• onDisabled(Context): Se llama cuando se quita la última instancia activa del proveedor.
• onReceive(Context, Intent): Intercepta cada transmisión de la plataforma antes de los métodos de devolución de llamada específicos. Debes asegurarte de que cualquier lógica del receptor personalizada que escribas llame a super.onReceive(context, intent) y nunca llame a goAsync por tu cuenta, ya que Glance enruta el trabajo de forma asíncrona automáticamente.

Cómo recibir intents de emisión del widget

De forma interna, GlanceAppWidgetReceiver filtra y controla las siguientes intents de transmisión de widgets de la plataforma fundamentales:

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

Crea la IU

En el siguiente fragmento, se muestra cómo crear la IU:

/* Import Glance Composables
 In the event there is a name clash with the Compose classes of the same name,
 you may rename the imports per https://kotlinlang.org/docs/packages.html#imports
 using the `as` keyword.

import androidx.glance.Button
import androidx.glance.layout.Column
import androidx.glance.layout.Row
import androidx.glance.text.Text
*/
class MyAppWidget : GlanceAppWidget() {

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        // Load data needed to render the AppWidget.
        // Use `withContext` to switch to another thread for long running
        // operations.

        provideContent {
            // create your AppWidget here
            MyContent()
        }
    }

    @Composable
    private fun MyContent() {
        Column(
            modifier = GlanceModifier.fillMaxSize(),
            verticalAlignment = Alignment.Top,
            horizontalAlignment = Alignment.CenterHorizontally
        ) {
            Text(text = "Where to?", modifier = GlanceModifier.padding(12.dp))
            Row(horizontalAlignment = Alignment.CenterHorizontally) {
                Button(
                    text = "Home",
                    onClick = actionStartActivity<MyActivity>()
                )
                Button(
                    text = "Work",
                    onClick = actionStartActivity<MyActivity>()
                )
            }
        }
    }
}
GlanceSnippets.kt

La muestra de código anterior hace lo siguiente:

• En el Column de nivel superior, los elementos se colocan verticalmente uno después del otro.
• El elemento Column expande su tamaño para que coincida con el espacio disponible (a través de GlanceModifier y alinea su contenido en la parte superior (verticalAlignment) y lo centra horizontalmente (horizontalAlignment).
• El contenido de Column se define con la expresión lambda. El orden es importante.
  • El primer elemento de Column es un componente Text con 12.dp de padding.
  • El segundo elemento es un Row, en el que los elementos se colocan horizontalmente uno después del otro, con dos Buttons centrados horizontalmente (horizontalAlignment). La visualización final depende del espacio disponible. La siguiente imagen es un ejemplo de cómo podría verse:

Puedes cambiar los valores de alineación o aplicar diferentes valores de modificadores (como padding) para cambiar la ubicación y el tamaño de los componentes. Consulta la documentación de referencia para obtener una lista completa de los componentes, los parámetros y los modificadores disponibles para cada clase.

Cómo implementar esquinas redondeadas

Android 12 introduce parámetros del sistema para personalizar los radios de las esquinas de los widgets de tu app de forma dinámica:

• system_app_widget_background_radius: Especifica el radio de la esquina del contenedor de fondo del widget (nunca superior a 28 dp).
• Radio interior: Para evitar el recorte de contenido, calcula un radio proporcional para tu contenido interior en función del contorno del fondo del sistema: systemRadiusValue - widgetPadding

En Glance, puedes aplicar propiedades de tamaño del radio de esquina de forma dinámica en la composición con GlanceModifier.cornerRadius(android.R.dimen.system_app_widget_background_radius).

Para garantizar la retrocompatibilidad en dispositivos que ejecutan Android 11 (nivel de API 30) o versiones anteriores, implementa atributos personalizados y recursos de temas personalizados alternativos:

• /values/attrs.xml

  <resources>
  <attr name="backgroundRadius" format="dimension" />
  </resources>
  

• /values/styles.xml

  <resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
  </resources>
  

• /values-31/styles.xml

  <resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
  </resources>
  

• /drawable/my_widget_background.xml

  <shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  </shape>