เริ่มต้นใช้งานวิดเจ็ต

ข้อกำหนดเบื้องต้นและการตั้งค่า

ก่อนที่จะเริ่มต้น โปรดตรวจสอบว่าสภาพแวดล้อมของคุณเป็นไปตามข้อกำหนดต่อไปนี้

ข้อกำหนดรันไทม์

วิดเจ็ต Wear ต้องใช้ com.google.android.wearable.protolayout.renderer APK เวอร์ชัน 1.6.1 ขึ้นไป ในอุปกรณ์เป้าหมาย

รับ Renderer เวอร์ชันที่เข้ากันได้ด้วยวิธีใดวิธีหนึ่งต่อไปนี้

  • โปรแกรมจำลอง Wear OS 7: ใช้รูปภาพโปรแกรมจำลอง Wear OS 7 ไม่เหมาะกับเวอร์ชันที่ต่ำกว่า 7 ดูวิธีการตั้งค่าได้ที่ตั้งค่าโปรแกรมจำลอง Wear OS 7 emulator
  • อุปกรณ์จริง: ใช้อุปกรณ์ Wear OS จริงที่ได้รับการอัปเดตอัตโนมัติ จาก Google Play Store หรืออุปกรณ์สำหรับนักพัฒนาแอปที่ลงชื่อเข้าใช้ Google Play Store

หากต้องการตรวจสอบเวอร์ชันที่ติดตั้งในอุปกรณ์ ให้ใช้คำสั่งต่อไปนี้

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

การกำหนดค่า Gradle

ไลบรารีวิดเจ็ต Wear มีให้บริการใน Google Maven

1. กำหนดค่า SDK เวอร์ชัน

ตรวจสอบว่าได้ตั้งค่า compileSdk และ targetSdk เป็น 37 ขึ้นไป

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

2. เพิ่มทรัพยากร Dependency

รวมทรัพยากร Dependency ต่อไปนี้ในไฟล์ build.gradle.kts ของแอป

ดึงดูด

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

Kotlin

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

สร้างวิดเจ็ต Hello World

วิดเจ็ต Wear ประกอบด้วยบริการที่ขยาย GlanceWearWidgetService และคลาสวิดเจ็ต ที่ขยาย GlanceWearWidget UI กำหนดโดยใช้ฟังก์ชัน @RemoteComposable ฟังก์ชัน @RemoteComposable

กำหนดบริการ

บริการคือจุดเริ่มต้นที่ระบบเชื่อมโยง

หากต้องการกำหนดวิดเจ็ต ให้สร้างบริการที่ขยาย GlanceWearWidgetService เนื่องจากไลบรารีนี้อยู่ระหว่างการพัฒนาอย่างต่อเนื่อง API บางรายการจึงถูกจำกัดในขณะที่กำลังปรับชื่อและโครงสร้างสุดท้าย การใช้คำอธิบายประกอบ @SuppressLint("RestrictedApi") จะบอกคอมไพเลอร์ว่าคุณ จงใจใช้ฟีเจอร์ใหม่ที่กำลังพัฒนาเหล่านี้ ข้อกำหนดนี้เป็นแบบชั่วคราวและจะถูกนำออกเมื่อ API เสร็จสมบูรณ์ในรุ่นเสถียรในอนาคต

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

กำหนดวิดเจ็ต

คลาสวิดเจ็ตมีข้อมูลและเลย์เอาต์สำหรับวิดเจ็ต

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

กำหนดเนื้อหา

เนื้อหาจะสร้างขึ้นโดยใช้คอมโพเนนต์ Remote Compose

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

สร้าง XML การกำหนดค่าวิดเจ็ต

สร้างไฟล์ใหม่ res/xml/hello_widget_info.xml เพื่อกำหนดพร็อพเพอร์ตี้และขนาดที่รองรับของวิดเจ็ต ดูข้อมูลอ้างอิงทั้งหมดของแอตทริบิวต์ XML ที่รองรับในแท็ก <wearwidget-provider> ได้ที่เอกสารประกอบ 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>

ลงทะเบียนใน AndroidManifest.xml

ลงทะเบียนบริการใน AndroidManifest.xml ด้วยตัวกรอง Intent และข้อมูลเมตาที่จำเป็น

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

สร้างและติดตั้งใช้งาน

หลังจากกำหนดบริการและวิดเจ็ตแล้ว คุณสามารถสร้างโปรเจ็กต์และติดตั้งใช้งานในอุปกรณ์หรือโปรแกรมจำลอง

สร้างและติดตั้ง

สร้างโปรเจ็กต์และติดตั้ง 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

2. แสดงวิดเจ็ต:

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

นอกจากนี้ คุณยังใช้การแสดงตัวอย่างของ Android Studio เพื่อช่วยทดสอบเลย์เอาต์ในหน้าจอขนาดต่างๆ ได้ด้วย