Widget 使用入门

前提条件和设置

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

运行时要求

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

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

  • 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 微件库可在 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-alpha11"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha11"
    implementation "androidx.glance.wear:wear:1.0.0-alpha10"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha10"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha04"

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

Kotlin

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

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

构建 Hello World 微件

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

定义服务

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

如需定义微件，请创建扩展 GlanceWearWidgetService 的服务。

class HelloWidgetService : GlanceWearWidgetService() {
    override val widget: GlanceWearWidget = HelloWidget()
}

定义微件

微件类提供微件的数据和布局。

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

定义内容

内容使用 Remote Compose 组件构建。

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

创建微件配置 XML

创建一个新文件 res/xml/hello_widget_info.xml，以定义微件的属性和支持的尺寸。如需查看 <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>

在 AndroidManifest.xml 中注册

使用所需的 intent 过滤器和元数据在 AndroidManifest.xml 中注册服务。

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

构建和部署

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

构建和安装

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

./gradlew :app:installDebug

添加和预览微件

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

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

1. 将微件添加到轮播界面：

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

**2. 显示微件：

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

Android Studio 预览版也可帮助您测试不同屏幕尺寸下的布局。