Criar um widget de app com o Glance

As seções a seguir descrevem como criar um widget de app simples com o Glance.

Importante: o Glance oferece uma abordagem moderna para criar widgets de apps usando o Compose, mas é restrito pelas limitações de AppWidgets e RemoteViews. O Glance usa diferentes elementos combináveis da interface do Jetpack Compose.

Declarar AppWidget no manifesto

Depois de concluir as etapas de configuração, declare o AppWidget e os metadados dele no app.

1. Registre o provedor do widget de app no seu arquivo AndroidManifest.xml e no arquivo de metadados associado:

<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. Estenda o receptor AppWidget de GlanceAppWidgetReceiver:

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

Adicione os metadados AppWidgetProviderInfo.

Em seguida, siga esta etapa para adicionar os metadados AppWidgetProviderInfo:

1. Siga o guia Criar um widget simples para criar e definir as informações do widget do app no arquivo @xml/my_app_widget_info.

   A única diferença do Glance é que não há nenhum XML initialLayout, mas você precisa definir um. Você pode usar o layout de carregamento predefinido fornecido na 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

Definir GlanceAppWidget

1. Crie uma nova classe que se estenda de GlanceAppWidget e modifique o método provideGlance. Este é o método em que você pode carregar dados necessários para renderizar o widget:

   Observação: provideGlance é executado na linha de execução principal. Para executar operações de longa duração em provideGlance, alterne para outra linha de execução usando withContext. Consulte Usar corrotinas para segurança principal para mais detalhes sobre como executar fora da linha de execução principal.

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. Instancie-o no glanceAppWidget no seu GlanceAppWidgetReceiver:

class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {

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

Você configurou um AppWidget usando o Glance.

Criar interface

O snippet a seguir demonstra como criar a interface:

/* 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<MainActivity>()
                )
                Button(
                    text = "Work",
                    onClick = actionStartActivity<MainActivity>()
                )
            }
        }
    }
}
GlanceSnippets.kt

O exemplo de código anterior faz o seguinte:

• No Column de nível superior, os itens são colocados um após o outro.
• O Column expande o tamanho para corresponder ao espaço disponível (usando o GlanceModifier), alinha o conteúdo à parte superior (verticalAlignment) e o centraliza horizontalmente (horizontalAlignment).
• O conteúdo do Column é definido usando a lambda. A ordem é importante.
  • O primeiro item em Column é um componente Text com 12.dp de padding.
  • O segundo item é uma Row, em que os itens são colocados horizontalmente, um após o outro, com dois Buttons centralizados horizontalmente (horizontalAlignment). A exibição final depende do espaço disponível. A imagem abaixo é um exemplo de como isso pode ficar:

Figura 1. Uma interface de exemplo.

É possível mudar os valores de alinhamento ou aplicar diferentes valores de modificadores, como padding, para mudar a posição e o tamanho dos componentes. Consulte a documentação de referência para ver uma lista completa de componentes, parâmetros e modificadores disponíveis para cada classe.