Mulai menggunakan widget

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

Keterampilan Android

Lihat di GitHub

Widget Wear OS

Gunakan keterampilan Android untuk membantu Anda membuat widget Wear OS dengan Glance, RemoteViews, dan ProtoLayout.

Untuk menginstal skill dari Android CLI, jalankan:

android skills add wear-widgets

Prasyarat dan Penyiapan

Sebelum memulai, pastikan lingkungan Anda memenuhi persyaratan berikut.

Persyaratan Runtime

Widget Wear memerlukan versi 1.6.1 atau yang lebih tinggi dari APK com.google.android.wearable.protolayout.renderer 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 Widget Wear 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:

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

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 Service

Layanan adalah titik entri yang diikat oleh 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 brush latar belakang widget Anda langsung ke WearWidgetDocument(background = ...) agar sistem host dapat menggambar dan menyamarkan latar belakang ke bentuk penampung OEM native. Menyetel kanvas transparan atau hitam dan menggambar penampung bulat kustom di dalam tata letak dapat menyebabkan cacat kotak mengambang dan tampilan lebar di beberapa perangkat.

Menentukan Konten

Konten dibuat menggunakan komponen Remote Compose.

@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 container root Anda menggunakan RemoteModifier.fillMaxSize(). Karena dimensi DP penampung dan inset aman bervariasi di berbagai model smartwatch, melakukan hardcode pada dimensi tetap atau padding luar dapat menyebabkan pemotongan atau tata letak yang tidak sejajar.

Melihat pratinjau widget di Android Studio

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

Suite pratinjau standar

Library wear-tooling-preview menyediakan suite PreviewParameterProvider yang telah ditetapkan 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.
• Rectangular Suite (RectangularAllWidgetPreviewParams): Penampung persegi panjang yang tidak dipangkas dengan padding yang aman. Gambar yang dihasilkan dengan konfigurasi pratinjau ini cocok untuk digunakan sebagai gambar pratinjau yang disematkan 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 membuat instance class widget dengan meneruskan lambda konten dan kuas latar belakang ke WearWidgetPreview.

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

Membuat aset gambar pratinjau

Atribut previewImage elemen <container> mereferensikan 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 menghasilkan 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 platform Design untuk composable pratinjau.
2. Di jendela pratinjau, klik kanan pratinjau yang dirender atau gunakan toolbar pratinjau untuk memilih Copy Image atau menyimpan 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 Anda 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 secara terprogram ke carousel dan menampilkannya di layar.

Catatan: Widget Wear menggunakan infrastruktur kartu yang mendasarinya untuk tujuan proses debug. Oleh karena itu, 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 kartu FULLSCREEN secara default. Anda juga dapat menentukan ukuran LARGE dan SMALL dengan meneruskan --ei type [0|1|2] ke perintah (dengan jenis 0 adalah FULLSCREEN). Bergantung pada status perangkat, update konten yang dipicu aplikasi menggunakan triggerUpdate() mungkin gagal untuk jenis non-layar penuh saat menggunakan versi library Widget Wear hingga 1.0.0-alpha10 (masalah ini telah diperbaiki mulai 1.0.0-alpha11).

2. Tampilkan 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 mengupdate instance widget tertentu tanpa memuat ulang semua instance aktif, panggil triggerUpdate dengan ID instance target.