Mulai menggunakan widget

Catatan: Tutorial ini mengasumsikan bahwa Anda sedang membuat widget baru dan tidak memiliki kartu yang sudah ada. Jika Anda mengupdate aplikasi yang sudah memiliki kartu yang ada, baca panduan Bermigrasi dari kartu ke widget untuk mengonfigurasi layanan Anda.

Prasyarat dan Penyiapan

Sebelum memulai, pastikan lingkungan Anda memenuhi persyaratan berikut.

Persyaratan Runtime

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

Dapatkan versi kompatibel perender dengan salah satu cara berikut:

• Emulator Wear OS 7: Gunakan image emulator Wear OS 7. Versi di bawah 7 tidak sesuai. 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 Widget Wear tersedia di Google Maven.

1. Konfigurasi 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 di file build.gradle.kts aplikasi Anda:

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

Membangun Widget Halo Dunia

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

Menentukan Layanan

Layanan adalah titik entri yang diikat sistem.

Untuk menentukan widget, buat layanan yang memperluas GlanceWearWidgetService dan anotasikan dengan @AssociateWithGlanceWearWidget, untuk mengaitkan layanan dengan class GlanceWearWidget yang sesuai.

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

Menentukan Widget

Class widget menyediakan data dan tata letak untuk widget.

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

Peringatan: Selalu berikan kuas latar belakang widget Anda langsung ke WearWidgetDocument(background = ...) sehingga sistem host dapat melukis dan memasker latar belakang ke bentuk penampung OEM asli. Menetapkan kanvas transparan atau hitam dan menggambar penampung bulat kustom di dalam tata letak dapat menyebabkan cacat kotak mengambang dan letterboxing di beberapa perangkat.

Menentukan Konten

Konten dibuat menggunakan komponen Compose Jarak Jauh.

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

Peringatan: Pastikan composable penampung root Anda menggunakan RemoteModifier.fillMaxSize(). Karena dimensi DP penampung dan inset aman berbeda di berbagai model smartwatch, pengodean tetap dimensi atau padding luar dapat menyebabkan kliping atau tata letak yang tidak sejajar.

Melihat pratinjau widget di Android Studio

Anda dapat melihat pratinjau tata letak widget secara langsung di panel Design Android Studio menggunakan androidx.glance.wear:wear-tooling-preview.

Kumpulan pratinjau standar

Library wear-tooling-preview menyediakan rangkaian PreviewParameterProvider yang telah ditentukan sebelumnya untuk menguji tata letak Anda di berbagai bentuk penampung dan konfigurasi perangkat:

• Squircle Suite (SquircleAllWidgetPreviewParams): Penampung persegi panjang bulat.
• Round Suite (RoundAllWidgetPreviewParams): Penampung berbentuk pil.
• Rangkaian Persegi Panjang (RectangularAllWidgetPreviewParams): Kontainer persegi panjang tanpa pemangkasan dengan padding aman. Gambar yang dihasilkan dengan konfigurasi pratinjau ini cocok untuk digunakan sebagai gambar pratinjau yang disematkan di APK yang digunakan oleh pemilih widget (lihat Membuat aset gambar pratinjau).

Untuk melihat pratinjau widget di Android Studio, gunakan @WearWidgetPreview:

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

Tips: Anda juga dapat melihat pratinjau tata letak @RemoteComposable secara langsung tanpa meng-instance class widget dengan meneruskan lambda konten dan kuas latar belakang ke WearWidgetPreview.

Buat XML Konfigurasi Widget

Buat file res/xml/hello_widget_info.xml baru untuk menentukan properti dan ukuran yang didukung widget. 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

Membuat aset gambar pratinjau

Atribut previewImage elemen <container> merujuk ke aset drawable yang ditampilkan di alat pilih widget sistem. Untuk membuat aset pratinjau dengan batas dan kepadatan yang benar, gunakan Pratinjau Android Studio dengan RectangularAllWidgetPreviewParams (yang membuat varian pratinjau untuk penampung kecil dan besar) dan tentukan kepadatan layar smartwatch 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

Untuk mengekstrak gambar pratinjau yang dirender, selesaikan langkah-langkah berikut:

1. Di Android Studio, buka permukaan Desain untuk composable pratinjau.
2. Di jendela pratinjau, klik kanan pratinjau yang dirender atau gunakan toolbar pratinjau untuk memilih Salin Gambar atau simpan gambar. Atau, gunakan alat CLI atau skrip otomatis untuk mengekstrak pratinjau Compose.
3. Simpan file gambar kecil dan besar ke direktori res/drawable-nodpi/ aplikasi Anda, seperti res/drawable-nodpi/widget_preview_small.png dan res/drawable-nodpi/widget_preview_large.png.

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.

Membangun dan Menginstal

Bangun 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 dan menampilkannya di layar secara terprogram.

Catatan: Widget Wear menggunakan infrastruktur kartu dasar untuk tujuan pen-debug-an. Akibatnya, perintah adb memerlukan operasi add-tile dan show-tile.

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

Catatan: Perintah sebelumnya menambahkan petak LAYAR PENUH secara default. Anda juga dapat menentukan ukuran BESAR dan KECIL dengan meneruskan --ei type [0|1|2] ke perintah (dengan jenis 0 adalah LAYAR PENUH). Bergantung pada status perangkat, update konten yang dipicu aplikasi menggunakan triggerUpdate() mungkin gagal untuk jenis non-layar penuh saat menggunakan library Wear Widget versi hingga 1.0.0-alpha10 (hal ini diperbaiki mulai dari 1.0.0-alpha11).

2. Menampilkan widget:

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

Memperbarui konten widget secara terprogram

Saat data pokok aplikasi Anda berubah (seperti menerima sinkronisasi data, notifikasi push, atau tindakan pengguna), beri tahu sistem untuk memuat ulang konten widget.

Untuk meminta update untuk semua instance aktif widget Anda, panggil triggerUpdateAll di class widget Anda:

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

Untuk memperbarui instance widget tertentu tanpa memuat ulang semua instance aktif, panggil triggerUpdate dengan ID instance target.