開始使用小工具

事前準備和設定

開始前，請確認您的環境符合下列需求。

執行階段要求

目標裝置上的 com.google.android.wearable.protolayout.renderer APK 必須為 1.6.1 以上版本，才能使用 Wear 小工具。

請透過下列任一方式取得相容的轉譯器版本：

  • 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-alpha19"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha19"
    implementation "androidx.glance.wear:wear:1.0.0-alpha18"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha18"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha11"

    // Tooling for previews (optional, but recommended)
    implementation "androidx.compose.remote:remote-tooling-preview:1.0.0-alpha19"
    implementation "androidx.wear.compose:compose-ui-tooling:1.6.2"
    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-alpha19")
    implementation("androidx.compose.remote:remote-core:1.0.0-alpha19")
    implementation("androidx.glance.wear:wear:1.0.0-alpha18")
    implementation("androidx.glance.wear:wear-core:1.0.0-alpha18")
    implementation("androidx.wear.compose.remote:remote-material3:1.0.0-alpha11")

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

建構 Hello World 小工具

Wear 小工具包含擴充 GlanceWearWidgetService 的服務，以及擴充 GlanceWearWidget 的小工具類別。您可以使用 @RemoteComposable 函式定義 UI。

定義服務

系統會繫結至這個服務做為進入點。

如要定義小工具，請建立擴充 GlanceWearWidgetService 的服務。

@AssociateWithGlanceWearWidget(HelloWidget::class)
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()
        }
    }
}

定義內容

內容是使用遠端 Compose 元件建構而成。

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

在 Android Studio 中預覽小工具

您可以使用 androidx.glance.wear:wear-tooling-preview，直接在 Android Studio 的「Design」面板中預覽小工具版面配置。

預先定義的預覽套件

wear-tooling-preview 程式庫提供預先定義的PreviewParameterProvider套件，可測試不同容器形狀和裝置設定的版面配置：

  • 方圓形套裝組合 (SquircleAllWidgetPreviewParams)：圓角矩形容器。
  • 圓形套件 (RoundAllWidgetPreviewParams)：膠囊形容器。
  • 矩形套裝組合 (RectangularAllWidgetPreviewParams)：未經裁剪的矩形容器，並提供安全邊框間距。使用這項預先發布版設定生成的圖片，適合做為小工具挑選器使用的 APK 內嵌預覽圖片 (請參閱「產生預覽圖片資產」)。

如要在 Android Studio 中預覽小工具，請使用 @WearWidgetPreview：

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

建立小工具設定 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>

生成預覽圖片素材資源

<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,
    )
}

如要擷取算繪的預覽圖片，請完成下列步驟：

  1. 在 Android Studio 中，開啟預覽可組合項目的「Design」介面。
  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 中註冊服務，並提供必要的意圖篩選器和中繼資料。

<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