Widget 使用入门

注意： 本教程假定您正在构建新 widget，并且没有现有功能块。如果您要更新已包含现有功能块的应用，请阅读从功能块迁移到 widget 指南来配置服务。

前提条件和设置

在开始之前，请确保您的环境满足以下要求。

运行时要求

Wear Widget 需要目标设备上安装 com.google.android.wearable.protolayout.renderer APK 的版本为 1.6.1 或更高版本。

您可以通过以下任一方式获取兼容版本的渲染器：

• Wear OS 7 模拟器：使用 Wear OS 7 模拟器映像。不适合使用低于 7 的版本。如需查看设置说明，请参阅设置 Wear OS 7 模拟器。
• 实体设备：使用可从 Google Play 商店接收自动更新的实体 Wear OS 设备，或已登录 Google Play 商店的开发者设备。

如需查看设备上安装的版本，请使用以下命令：

adb shell dumpsys package com.google.android.wearable.protolayout.renderer | \
  grep -m 1 versionName | \
  awk -F= '{print $2}'

Gradle 配置

Wear widget 库可在 Google Maven 上找到。

1. 配置 SDK 版本

确保将 compileSdk 和 targetSdk 设置为 37 或更高版本。

android {
    compileSdk = 37
    // ...
    defaultConfig {
        targetSdk = 37
        // ...
    }
}

2. 添加依赖项

在应用的 build.gradle.kts 文件中添加以下依赖项：

Groovy

dependencies {
    // Core Wear Widget and Remote Compose libraries
    implementation "androidx.compose.remote:remote-creation-compose:1.0.0-alpha20"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha20"
    implementation "androidx.glance.wear:wear:1.0.0-alpha19"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha19"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha12"

    // Tooling for previews (optional, but recommended)
    implementation "androidx.compose.remote:remote-tooling-preview:1.0.0-alpha20"
    implementation "androidx.wear.compose:compose-ui-tooling:1.7.0"
    implementation "androidx.wear.tiles:tiles-tooling-preview:1.6.2"
    debugImplementation "androidx.wear.tiles:tiles-renderer:1.6.2"
}

Kotlin

dependencies {
    // Core Wear Widget and Remote Compose libraries
    implementation("androidx.compose.remote:remote-creation-compose:1.0.0-alpha20")
    implementation("androidx.compose.remote:remote-core:1.0.0-alpha20")
    implementation("androidx.glance.wear:wear:1.0.0-alpha19")
    implementation("androidx.glance.wear:wear-core:1.0.0-alpha19")
    implementation("androidx.wear.compose.remote:remote-material3:1.0.0-alpha12")

    // Tooling for previews (optional, but recommended)
    implementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha20")
    implementation("androidx.wear.compose:compose-ui-tooling:1.7.0")
    implementation("androidx.wear.tiles:tiles-tooling-preview:1.6.2")
    debugImplementation("androidx.wear.tiles:tiles-renderer:1.6.2")
}

构建 Hello World widget

Wear 微件由扩展 GlanceWearWidgetService 的服务和扩展 GlanceWearWidget 的微件类组成。您可以使用 @RemoteComposable 函数定义界面。

定义服务

该服务是系统绑定的入口点。

如需定义 widget，请创建一个扩展 GlanceWearWidgetService 的服务，并使用 @AssociateWithGlanceWearWidget 对其进行注释，以将该服务与相应的 GlanceWearWidget 类相关联。

@AssociateWithGlanceWearWidget(HelloWidget::class)
class HelloWidgetService : GlanceWearWidgetService() {
    override val widget: GlanceWearWidget = HelloWidget()
}
GetStarted.kt

定义 widget

widget 类提供 widget 的数据和布局。

class HelloWidget : GlanceWearWidget() {
    override suspend fun provideWidgetData(
        context: Context,
        params: WearWidgetParams,
    ): WearWidgetData {
        return WearWidgetDocument(
            background = WearWidgetBrush.color(Color.Blue.rc),
        ) {
            HelloWidgetContent()
        }
    }
}
GetStarted.kt

警告： 请务必将 widget 的背景画笔直接提供给 WearWidgetDocument(background = ...)，以便宿主系统能够将背景绘制并遮盖为 OEM 原生容器形状。在布局中设置透明或黑色画布并绘制自定义圆角容器可能会导致某些设备上出现浮动框和信箱模式缺陷。

定义内容

内容是使用远程 Compose 组件构建的。

@RemoteComposable
@Composable
fun HelloWidgetContent() {
    RemoteBox(
        modifier = RemoteModifier.fillMaxSize(),
        contentAlignment = RemoteAlignment.Center,
    ) {
        RemoteText(
            text = "Hello World".rs,
            color = Color.White.rc,
        )
    }
}
GetStarted.kt

警告： 请确保根容器可组合项使用 RemoteModifier.fillMaxSize()。由于容器 DP 维度和安全边衬区因手表型号而异，因此对固定维度或外部边衬区进行硬编码可能会导致剪裁或布局错位。

在 Android Studio 中预览 widget

您可以使用 androidx.glance.wear:wear-tooling-preview 直接在 Android Studio 的 Design 面板中预览 widget 布局。

预定义的预览版套件

wear-tooling-preview 库提供预定义的 PreviewParameterProvider 套件，用于在不同的容器形状和设备配置中测试布局：

• 方圆形套装 (SquircleAllWidgetPreviewParams)：圆角矩形容器。
• 圆形套件 (RoundAllWidgetPreviewParams)：药丸状容器。
• 矩形套装 (RectangularAllWidgetPreviewParams)：未裁剪的矩形容器，带有安全边衬区。使用此预览版配置生成的图片适合用作微件选择器使用的 APK 嵌入式预览图片（请参阅生成预览图片资源）。

如需在 Android Studio 中预览 widget，请使用 @WearWidgetPreview：

@Preview
@Composable
fun HelloWidgetPreview(
    @PreviewParameter(SquircleAllWidgetPreviewParams::class) params: WearWidgetParams,
) {
    WearWidgetPreview(
        widget = HelloWidget(),
        params = params,
    )
}
GetStarted.kt

提示： 您还可以通过将内容 lambda 和背景画笔传递给 WearWidgetPreview，直接预览 @RemoteComposable 布局，而无需实例化 widget 类。

创建 widget 配置 XML

创建一个新文件 res/xml/hello_widget_info.xml 来定义 widget 的属性和支持的大小。如需查看 <wearwidget-provider> 标记中受支持的 XML 属性的完整参考信息，请参阅 WearWidgetProviderInfo 文档。

<wearwidget-provider
    description="@string/hello_widget_description"
    icon="@mipmap/ic_launcher"
    label="@string/hello_widget_label"
    preferredType="SMALL">

    <container
        type="SMALL"
        previewImage="@drawable/widget_preview_small" />
    <container
        type="LARGE"
        previewImage="@drawable/widget_preview_large" />
</wearwidget-provider>
hello_widget_info.xml

生成预览图片素材资源

<container> 元素的 previewImage 属性引用了在系统微件选择器中显示的可绘制对象资源。如需生成具有正确边界和密度的预览资源，请将 Android Studio 预览版与 RectangularAllWidgetPreviewParams（可为小型容器和大型容器生成预览变体）搭配使用，并指定 320 DPI 的智能手表显示屏密度：

@Preview(
    name = "Widget Preview Asset",
    device = "spec:width=1000dp,height=1000dp,dpi=320",
)
@Composable
fun HelloWidgetCatalogPreview(
    @PreviewParameter(RectangularAllWidgetPreviewParams::class) params: WearWidgetParams,
) {
    WearWidgetPreview(
        widget = HelloWidget(),
        params = params,
    )
}
GetStarted.kt

如需提取渲染的预览图片，请完成以下步骤：

1. 在 Android Studio 中，打开预览可组合项的设计界面。
2. 在预览窗口中，右键点击渲染的预览内容，或使用预览工具栏选择复制图片或保存图片。或者，您也可以使用 CLI 工具或自动化脚本提取 Compose 预览。
3. 将小图片文件和大图片文件保存到应用的 res/drawable-nodpi/ 目录中，例如 res/drawable-nodpi/widget_preview_small.png 和 res/drawable-nodpi/widget_preview_large.png。

在 AndroidManifest.xml 中注册

在 AndroidManifest.xml 中注册服务，并提供所需的 intent 过滤器和元数据。

<service
    android:name=".snippets.widget.HelloWidgetService"
    android:exported="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/hello_widget_label"
    android:permission="com.google.android.wearable.permission.BIND_TILE_PROVIDER">

    <intent-filter>
        <action android:name="androidx.glance.wear.action.BIND_WIDGET_PROVIDER" />
        <!-- If you already have a Tile, omit the following line. -->
        <action android:name="androidx.wear.tiles.action.BIND_TILE_PROVIDER" />
    </intent-filter>

    <meta-data
        android:name="androidx.glance.wear.widget.provider"
        android:resource="@xml/hello_widget_info" />

    <meta-data
        android:name="androidx.wear.tiles.PREVIEW"
        android:resource="@drawable/tile_preview" />
</service>
AndroidManifest.xml

构建和部署

定义服务和 widget 后，您可以构建项目并将其部署到设备或模拟器。

构建和安装

构建项目并将调试 APK 安装到已连接的设备或模拟器上：

./gradlew :app:installDebug

添加并预览微件

安装应用后，使用 adb 以编程方式将 widget 添加到轮播界面，并在屏幕上显示。

注意：Wear widget 使用底层功能块基础架构进行调试。因此，adb 命令需要 add-tile 和 show-tile 操作。

1. 将 widget 添加到轮播界面：

adb shell am broadcast \
  -a com.google.android.wearable.app.DEBUG_SURFACE \
  --es operation add-tile \
  --ecn component <your_package_name>/.HelloWidgetService

注意： 上述命令默认添加一个全屏图块。您还可以通过将 --ei type [0|1|2] 传递给命令来指定 LARGE 和 SMALL 尺寸（其中类型 0 为全屏）。如果使用 Wear Widget 库版本 1.0.0-alpha10 或更低版本，则使用 triggerUpdate() 的应用触发的内容更新可能会因设备状态而失败（此问题已在 1.0.0-alpha11 中修复）。

2. 显示 widget：

adb shell am broadcast \
  -a com.google.android.wearable.app.DEBUG_SYSUI \
  --es operation show-tile \
  --ei index 0

以编程方式更新 widget 内容

当应用的基础数据发生变化时（例如收到数据同步、推送通知或用户操作），请通知系统刷新 widget 内容。

如需为 widget 的所有有效实例请求更新，请在 widget 类上调用 triggerUpdateAll：

// Request a content update for all active HelloWidget instances
HelloWidget().triggerUpdateAll(context)

如需更新特定 widget 实例而不刷新所有有效实例，请使用目标实例 ID 调用 triggerUpdate。