Mulai menggunakan widget

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 renderer yang kompatibel dengan salah satu cara berikut:

• Emulator Wear OS 7: Gunakan image emulator Wear OS 7. Versi di bawah 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:

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

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

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 ini adalah titik entri yang terikat dengan sistem.

Untuk menentukan widget, buat layanan yang memperluas GlanceWearWidgetService.

@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

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

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.

Paket pratinjau standar

Library wear-tooling-preview menyediakan paket PreviewParameterProvider standar untuk menguji tata letak Anda di berbagai bentuk penampung dan konfigurasi perangkat:

• Paket Persegi Bulat (SquircleAllWidgetPreviewParams): Penampung persegi panjang bulat.
• Paket Bulat (RoundAllWidgetPreviewParams): Penampung berbentuk pil.
• Paket Persegi Panjang (RectangularAllWidgetPreviewParams): Penampung persegi panjang yang tidak dipangkas dengan padding 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

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 pemilih 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 tampilan 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 res/drawable-nodpi/ direktori 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.

Build dan Instal

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: Widget Wear 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