ウィジェットを使ってみる

注: このチュートリアルでは、新しいウィジェットを作成し、既存のタイルがないことを前提としています。既存のタイルがすでにあるアプリを更新する場合は、タイルからウィジェットに移行するガイドを読んで、サービスを構成してください。

Android のスキル

GitHub で表示

Wear OS ウィジェット

Android スキルを使用して、Glance、RemoteViews、ProtoLayout で Wear OS ウィジェットを構築します。

Android CLI からスキルをインストールするには、次のコマンドを実行します。

android skills add wear-widgets

前提条件と設定

始める前に、環境が次の要件を満たしていることを確認してください。

ランタイム要件

Wear ウィジェットを使用するには、対象デバイスに 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-alpha21"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha21"
    implementation "androidx.glance.wear:wear:1.0.0-alpha20"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha20"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha13"

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

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

Hello World ウィジェットを作成する

Wear ウィジェットは、GlanceWearWidgetService を拡張するサービスと、GlanceWearWidget を拡張するウィジェット クラスで構成されます。UI は @RemoteComposable 関数を使用して定義します。

Service を定義する

サービスは、システムがバインドするエントリ ポイントです。

ウィジェットを定義するには、GlanceWearWidgetService を拡張するサービスを作成し、@AssociateWithGlanceWearWidget でアノテーションを付けて、サービスを適切な GlanceWearWidget クラスに関連付けます。

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

ウィジェットを定義する

ウィジェット クラスは、ウィジェットのデータとレイアウトを提供します。

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

警告: ウィジェットの背景ブラシは、常に WearWidgetDocument(background = ...) に直接指定してください。これにより、ホストシステムが背景をネイティブ OEM コンテナの形状にペイントしてマスクできるようになります。透明または黒のキャンバスを設定し、レイアウト内にカスタムの角丸コンテナを描画すると、一部のデバイスでフローティング ボックスとレターボックスの不具合が発生する可能性があります。

コンテンツを定義する

コンテンツは Remote 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 でウィジェットをプレビューする

androidx.glance.wear:wear-tooling-preview を使用して、Android Studio の [Design] パネルでウィジェット レイアウトを直接プレビューできます。

事前定義されたプレビュー スイート

wear-tooling-preview ライブラリには、さまざまなコンテナ形状やデバイス設定でレイアウトをテストするための事前定義された PreviewParameterProvider スイートが用意されています。

• Squircle Suite（SquircleAllWidgetPreviewParams）: 角丸長方形のコンテナ。
• Round Suite（RoundAllWidgetPreviewParams）: 錠剤型のコンテナ。
• 長方形スイート（RectangularAllWidgetPreviewParams）: 安全なパディングが施された、切り抜かれていない長方形のコンテナ。このプレビュー構成で生成された画像は、ウィジェット選択ツールで使用される APK 埋め込みプレビュー画像として使用するのに適しています（プレビュー画像アセットを生成するをご覧ください）。

Android Studio でウィジェットをプレビューするには、@WearWidgetPreview を使用します。

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

ヒント: コンテンツ ラムダと背景ブラシを WearWidgetPreview に渡すことで、ウィジェット クラスをインスタンス化せずに @RemoteComposable レイアウトを直接プレビューすることもできます。

ウィジェット構成 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>
hello_widget_info.xml

プレビュー画像アセットを生成する

<container> 要素の previewImage 属性は、システム ウィジェット選択ツールに表示されるドローアブル アセットを参照します。正しい境界と密度でプレビュー用アセットを生成するには、RectangularAllWidgetPreviewParams を指定した Android Studio プレビューを使用し（これにより、小さいコンテナと大きいコンテナの両方のプレビュー バリアントが生成されます）、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 で、プレビュー コンポーザブルの [Design] サーフェスを開きます。
2. プレビュー ウィンドウで、レンダリングされたプレビューを右クリックするか、プレビュー ツールバーを使用して [Copy Image] を選択するか、画像を保存します。または、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>
AndroidManifest.xml

ビルドとデプロイ

サービスとウィジェットを定義したら、プロジェクトをビルドしてデバイスまたはエミュレータにデプロイできます。

ビルドとインストール

プロジェクトをビルドし、接続済みのデバイスまたはエミュレータにデバッグ 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

注: 上記のコマンドは、デフォルトで FULLSCREEN タイルを追加します。--ei type [0|1|2] をコマンドに渡すことで、LARGE サイズと SMALL サイズを指定することもできます（タイプ 0 は FULLSCREEN）。デバイスの状態によっては、Wear Widget ライブラリのバージョン 1.0.0-alpha10 までを使用している場合、triggerUpdate() を使用したアプリトリガーのコンテンツ更新が、全画面表示以外のタイプで失敗することがあります（これは 1.0.0-alpha11 以降で修正されています）。

2. ウィジェットを表示する:

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

プログラムでウィジェットのコンテンツを更新する

アプリの基盤となるデータが変更された場合（データ同期、プッシュ通知、ユーザー操作など）、ウィジェットのコンテンツを更新するようシステムに通知します。

ウィジェットのすべてのアクティブなインスタンスの更新をリクエストするには、ウィジェット クラスで triggerUpdateAll を呼び出します。

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

すべてのアクティブなインスタンスを更新せずに特定のウィジェット インスタンスを更新するには、ターゲット インスタンス ID を指定して triggerUpdate を呼び出します。