Mulai menggunakan widget

Prasyarat dan Penyiapan

Sebelum memulai, pastikan lingkungan Anda memenuhi persyaratan berikut.

Persyaratan Runtime

Wear Widget memerlukan APK com.google.android.wearable.protolayout.renderer versi 1.6.1 atau yang lebih tinggi di perangkat target.

Dapatkan versi perender yang kompatibel dengan salah satu cara berikut:

• Emulator Wear OS 7: Gunakan image emulator Wear OS 7. Versi yang lebih rendah dari 7 tidak cocok. Untuk mengetahui petunjuk penyiapan, lihat Menyiapkan emulator Wear OS 7.
• Perangkat Fisik: Gunakan perangkat Wear OS fisik yang menerima update otomatis dari Google Play Store, atau perangkat developer yang login ke Google Play Store.

Untuk memeriksa versi yang telah Anda instal di perangkat, gunakan perintah berikut:

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

Konfigurasi Gradle

Library Wear Widget tersedia di Google Maven.

1. Mengonfigurasi Versi SDK

Pastikan compileSdk dan targetSdk Anda ditetapkan ke 37 atau yang lebih tinggi.

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

2. Menambahkan Dependensi

Sertakan dependensi berikut dalam file build.gradle.kts aplikasi Anda:

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

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

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

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

Membangun Widget Halo Dunia

Wear Widget terdiri dari layanan yang memperluas GlanceWearWidgetService dan class widget yang memperluas GlanceWearWidget. UI ditentukan menggunakan fungsi @RemoteComposable. fungsi @RemoteComposable.

Menentukan Layanan

Layanan adalah titik entri yang terikat dengan sistem.

Untuk menentukan widget, buat layanan yang memperluas GlanceWearWidgetService. Karena library ini sedang dalam pengembangan aktif, API tertentu dibatasi saat nama dan struktur finalnya sedang disempurnakan. Menggunakan anotasi @SuppressLint("RestrictedApi") memberi tahu compiler bahwa Anda sengaja menggunakan fitur baru yang terus berkembang ini. Persyaratan ini bersifat sementara dan akan dihapus setelah API diselesaikan dalam rilis stabil mendatang.

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

Menentukan Widget

Class widget menyediakan data dan tata letak untuk widget.

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

Menentukan Konten

Konten dibuat menggunakan komponen Remote Compose.

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

Membuat XML Konfigurasi Widget

Buat file baru res/xml/hello_widget_info.xml untuk menentukan properti widget dan ukuran yang didukung. Untuk referensi lengkap atribut XML yang didukung dalam tag <wearwidget-provider>, lihat dokumentasi 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

Mendaftarkan di AndroidManifest.xml

Daftarkan layanan di AndroidManifest.xml dengan filter intent dan metadata yang diperlukan.

<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

Build dan Deploy

Setelah menentukan layanan dan widget, Anda dapat mem-build project dan men-deploy-nya ke perangkat atau emulator.

Mem-build dan Menginstal

Build project dan instal APK debug ke perangkat atau emulator yang terhubung:

./gradlew :app:installDebug

Menambahkan dan melihat pratinjau widget

Setelah aplikasi diinstal, gunakan adb untuk menambahkan widget ke carousel secara terprogram dan menampilkannya di layar.

Catatan: Wear Widget menggunakan infrastruktur kartu yang mendasarinya untuk tujuan proses debug. Oleh karena itu, perintah adb memerlukan add-tile dan show-tile operasi.

1. Tambahkan widget ke carousel:

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

2. Tampilkan widget:

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

Pratinjau Android Studio juga tersedia untuk membantu Anda menguji tata letak di berbagai ukuran layar.