Creare un widget dell'app con Riepilogo

Le sezioni seguenti descrivono come creare un semplice widget dell'app con Glance.

Punto chiave: Glance offre un approccio moderno per creare widget delle app utilizzando Compose, ma è limitato dalle limitazioni di AppWidgets e RemoteViews. Di conseguenza, Glance utilizza diversi componibili dell'UI di Jetpack Compose.

Dichiara AppWidget nel manifest

Dopo aver completato i passaggi di configurazione, dichiara AppWidget e i relativi nella tua app.

1. Registra il provider del widget dell'app nel file AndroidManifest.xml e il file di metadati associato:

<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

1. Estendi il ricevitore AppWidget da GlanceAppWidgetReceiver:

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

Aggiungi i metadati AppWidgetProviderInfo

A questo punto, segui questo passaggio per aggiungere i metadati AppWidgetProviderInfo:

1. Segui la guida Creare un widget semplice per creare e definire l'app. le informazioni del widget nel file @xml/my_app_widget_info.

   L'unica differenza con Glance è che non esiste un file XML initialLayout, ma devi definirne uno. Puoi utilizzare il layout di caricamento predefinito disponibile in nella libreria:

<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

Definisci GlanceAppWidget

1. Crea una nuova classe che si estende da GlanceAppWidget e sostituisce il provideGlance. Questo è il metodo in cui puoi caricare i dati necessari per il rendering del widget:

   Nota: provideGlance viene eseguito sul thread principale. Per eseguire applicazioni di lunga durata operazioni in provideGlance, passa a un altro thread utilizzando withContext. Consulta l'articolo Uso delle coroutine per la sicurezza principale per maggiori dettagli su come eseguire l'operazione all'esterno del thread principale.

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

1. Crea un'istanza in glanceAppWidget su GlanceAppWidgetReceiver:

class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {

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

Hai configurato AppWidget utilizzando la funzionalità Riepilogo.

Crea UI

Il seguente snippet mostra come creare la UI:

/* 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
            GlanceTheme {
                MyContent()
            }
        }
    }

    @Composable
    private fun MyContent() {
        Column(
            modifier = GlanceModifier.fillMaxSize()
                .background(GlanceTheme.colors.background),
            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

L'esempio di codice precedente esegue queste operazioni:

• Nel livello superiore Column, gli elementi vengono posizionati verticalmente uno dopo ogni e l'altro.
• Column espande le proprie dimensioni per adattarle allo spazio disponibile (tramite il tag GlanceModifier e allinea i suoi contenuti in alto (verticalAlignment) e la centra orizzontalmente (horizontalAlignment).
• I contenuti di Column vengono definiti utilizzando la funzione lambda. L'ordine è importante.
  • Il primo elemento in Column è un componente Text con 12.dp di spaziatura interna.
  • Il secondo elemento è una Row, con gli elementi posizionati in orizzontale uno dopo l'altro, con due Buttons centrati orizzontalmente (horizontalAlignment). La visualizzazione finale dipende dallo spazio disponibile. L'immagine seguente è un esempio del possibile aspetto:

Figura 1. Un esempio di UI.

Puoi cambiare i valori di allineamento o applicare valori di modifica diversi (ad esempio spaziatura interna) per modificare il posizionamento e le dimensioni dei componenti. Consulta il riferimento documentazione per un elenco completo di componenti, parametri e modificatori di ogni classe.