使用 Glance 创建应用 widget

以下部分介绍如何使用 Glance 创建简单的应用 widget。

要点 ：Glance 提供了一种使用 Compose 构建应用 widget 的新式方法， 但受 AppWidgets 和 RemoteViews 的限制。 因此，Glance 使用的可组合项与 Jetpack Compose 界面不同。

在清单中声明 AppWidget

完成设置步骤后，声明 AppWidget 及其 元数据。

1. 在 AndroidManifest.xml 文件中注册应用 widget 的提供程序 以及关联的元数据文件：

<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. 从 GlanceAppWidgetReceiver 扩展 AppWidget 接收器：

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

添加 AppWidgetProviderInfo 元数据

接下来，请按照以下步骤添加 AppWidgetProviderInfo 元数据：

1. 按照创建简单的 widget 指南创建和定义应用 @xml/my_app_widget_info 文件中的 widget 信息。

   Glance 的唯一不同之处在于没有 initialLayout XML， 您必须定义一个您可以使用 库：

<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

定义 GlanceAppWidget

1. 创建一个从 GlanceAppWidget 扩展的新类，并替换 provideGlance 方法。使用此方法，您可以加载 渲染 widget 所需的资源：

   注意 ：provideGlance 在主线程上运行。为了执行任何长时间运行的 操作，请使用 切换到另一个线程provideGlance withContext。如需详细了解以下内容，请参阅使用协程确保主线程安全 如何在主线程之外运行。

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. 在 GlanceAppWidgetReceiver 上的 glanceAppWidget 中将其实例化：

class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {

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

现在，您已使用 Glance 配置了一个 AppWidget。

创建界面

以下代码段演示了如何创建界面：

/* 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

上述代码示例将执行以下操作：

• 在顶级 Column 中，项会垂直排列，每个项紧接着放置一个。 其他。
• Column 会扩展其大小以匹配可用空间（通过 GlanceModifier，并将其内容与顶部对齐 (verticalAlignment) 并将其水平居中 (horizontalAlignment)。
• Column 的内容使用 lambda 进行定义。顺序很重要。
  • Column 中的第一项是 Text 组件，其 12.dp 为 内边距。
  • 第二项是 Row，其中多个项水平放置 两个 Buttons 并排显示，水平居中 （horizontalAlignment）。最终显示效果取决于可用空间。 下图是一个示例：

图 1. 界面示例。

您可以更改对齐方式值或应用不同的修饰符值（例如 内边距）来更改组件的位置和大小。请参阅参考文档 查看组件、参数和可用资源的完整列表 修饰符。