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

หมายเหตุ: บทแนะนำนี้ถือว่าคุณกำลังสร้างวิดเจ็ตใหม่และไม่มีการ์ดอยู่แล้ว หากคุณกำลังอัปเดตแอปที่มีการ์ดอยู่แล้ว โปรดอ่านคำแนะนำเรื่องการย้ายข้อมูลจากการ์ดไปยังวิดเจ็ตเพื่อกำหนดค่าบริการ

ทักษะ Android

ดูใน GitHub

วิดเจ็ต Wear OS

ใช้ทักษะ Android เพื่อช่วยคุณสร้างวิดเจ็ต Wear OS ด้วย Glance, RemoteViews และ ProtoLayout

หากต้องการติดตั้งทักษะจาก Android CLI ให้เรียกใช้คำสั่งต่อไปนี้

android skills add wear-widgets

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

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

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

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

รับโปรแกรมแสดงผลเวอร์ชันที่เข้ากันได้ด้วยวิธีใดวิธีหนึ่งต่อไปนี้

• โปรแกรมจำลอง Wear OS 7: ใช้อิมเมจโปรแกรมจำลอง Wear OS 7 เวอร์ชันที่ต่ำกว่า 7 ไม่เหมาะสำหรับการใช้งาน ดูวิธีการตั้งค่าได้ที่ตั้งค่าโปรแกรมจำลอง Wear OS 7
• อุปกรณ์จริง: ใช้อุปกรณ์ 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-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")
}

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

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

กำหนดบริการ

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

หากต้องการกำหนดวิดเจ็ต ให้สร้างบริการที่ขยาย GlanceWearWidgetService และใส่คำอธิบายประกอบด้วย @AssociateWithGlanceWearWidget เพื่อเชื่อมโยงบริการกับคลาส GlanceWearWidget ที่เหมาะสม

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

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

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

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

คำเตือน: ระบุแปรงพื้นหลังของวิดเจ็ตไปยัง WearWidgetDocument(background = ...) โดยตรงเสมอ เพื่อให้ระบบโฮสต์สามารถวาดและมาสก์พื้นหลังเป็นรูปร่างคอนเทนเนอร์ OEM แบบเนทีฟได้ การตั้งค่า Canvas สีดำหรือโปร่งใสและการวาดคอนเทนเนอร์โค้งมนที่กำหนดเองภายในเลย์เอาต์อาจทำให้เกิดข้อบกพร่องของกล่องลอยและแถบสีดำบนอุปกรณ์บางรุ่น

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

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

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

คำเตือน: ตรวจสอบว่า Composable ของคอนเทนเนอร์รูทใช้ RemoteModifier.fillMaxSize() เนื่องจากขนาด DP ของคอนเทนเนอร์และส่วนแทรกที่ปลอดภัยจะแตกต่างกันไปตามรุ่นของนาฬิกา การกำหนดขนาดคงที่หรือระยะห่างจากขอบด้านนอกแบบฮาร์ดโค้ดอาจทำให้เกิดการตัดหรือเลย์เอาต์ที่ไม่ตรงแนว

แสดงตัวอย่างวิดเจ็ตใน Android Studio

คุณสามารถดูตัวอย่างเลย์เอาต์วิดเจ็ตได้โดยตรงในแผงการออกแบบของ Android Studio โดยใช้ androidx.glance.wear:wear-tooling-preview

ชุดตัวอย่างที่กำหนดไว้ล่วงหน้า

ไลบรารี wear-tooling-preview มีชุด PreviewParameterProvider ที่กำหนดไว้ล่วงหน้าเพื่อทดสอบเลย์เอาต์ในรูปทรงคอนเทนเนอร์และการกำหนดค่าอุปกรณ์ต่างๆ ดังนี้

• Squircle Suite (SquircleAllWidgetPreviewParams): คอนเทนเนอร์สี่เหลี่ยมผืนผ้ามุมมน
• Round Suite (RoundAllWidgetPreviewParams): คอนเทนเนอร์รูปทรงแคปซูล
• ชุดสี่เหลี่ยมผืนผ้า (RectangularAllWidgetPreviewParams): คอนเทนเนอร์สี่เหลี่ยมผืนผ้าที่ไม่มีการครอบตัดพร้อมระยะห่างจากขอบที่ปลอดภัย รูปภาพที่สร้างขึ้นด้วยการกำหนดค่าตัวอย่างนี้เหมาะสำหรับใช้เป็นรูปภาพตัวอย่างที่ฝัง APK ซึ่งเครื่องมือเลือกวิดเจ็ตใช้ (ดูสร้างชิ้นงานรูปภาพตัวอย่าง)

หากต้องการดูตัวอย่างวิดเจ็ตใน Android Studio ให้ใช้ @WearWidgetPreview ดังนี้

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

เคล็ดลับ: คุณยังสามารถดูตัวอย่างเลย์เอาต์ @RemoteComposable ได้โดยตรงโดยไม่ต้องสร้างอินสแตนซ์คลาสวิดเจ็ตด้วยการส่งแลมบ์ดาเนื้อหาและแปรงพื้นหลังไปยัง WearWidgetPreview

สร้าง 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>
hello_widget_info.xml

สร้างชิ้นงานรูปภาพตัวอย่าง

แอตทริบิวต์ previewImage ขององค์ประกอบ <container> อ้างอิงชิ้นงานที่ถอนออกได้ซึ่งแสดงในเครื่องมือเลือกวิดเจ็ตของระบบ หากต้องการสร้างเนื้อหาตัวอย่างที่มีขอบเขตและความหนาแน่นที่ถูกต้อง ให้ใช้ตัวอย่าง Android Studio ที่มี RectangularAllWidgetPreviewParams (ซึ่งจะสร้างตัวแปรตัวอย่างสำหรับทั้งคอนเทนเนอร์ขนาดเล็กและขนาดใหญ่) และระบุความหนาแน่นของการแสดงผลสมาร์ทวอทช์ 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

หากต้องการดึงรูปภาพตัวอย่างที่แสดงผล ให้ทำตามขั้นตอนต่อไปนี้

1. ใน Android Studio ให้เปิดแพลตฟอร์มการออกแบบสำหรับตัวอย่าง Composable
2. ในหน้าต่างตัวอย่าง ให้คลิกขวาที่ตัวอย่างที่แสดงผลหรือใช้แถบเครื่องมือตัวอย่างเพื่อเลือกคัดลอกรูปภาพหรือบันทึกรูปภาพ หรือจะใช้เครื่องมือ CLI หรือสคริปต์อัตโนมัติเพื่อดึงข้อมูลตัวอย่าง Compose ก็ได้
3. บันทึกไฟล์ภาพขนาดเล็กและขนาดใหญ่ลงในไดเรกทอรี res/drawable-nodpi/ ของแอป เช่น res/drawable-nodpi/widget_preview_small.png และ res/drawable-nodpi/widget_preview_large.png

ลงทะเบียนใน 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>
AndroidManifest.xml

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

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

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

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

หมายเหตุ: คำสั่งข้างต้นจะเพิ่มการ์ดแบบเต็มหน้าจอโดยค่าเริ่มต้น นอกจากนี้ คุณยังระบุขนาด LARGE และ SMALL ได้โดยส่ง --ei type [0|1|2] ไปยังคำสั่ง (โดยที่ประเภท 0 คือ FULLSCREEN) การอัปเดตเนื้อหาที่แอปเรียกให้แสดงโดยใช้ triggerUpdate() อาจไม่สำเร็จสำหรับประเภทที่ไม่ใช่แบบเต็มหน้าจอเมื่อใช้ไลบรารีวิดเจ็ต Wear เวอร์ชันไม่เกิน 1.0.0-alpha10 (ปัญหานี้ได้รับการแก้ไขแล้วตั้งแต่เวอร์ชัน 1.0.0-alpha11 เป็นต้นไป) ทั้งนี้ขึ้นอยู่กับสถานะของอุปกรณ์

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

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

อัปเดตเนื้อหาวิดเจ็ตแบบเป็นโปรแกรม

เมื่อข้อมูลเบื้องหลังของแอปมีการเปลี่ยนแปลง (เช่น ได้รับการซิงค์ข้อมูล ข้อความ Push หรือการดำเนินการของผู้ใช้) ให้แจ้งระบบเพื่อรีเฟรชเนื้อหาวิดเจ็ต

หากต้องการขออัปเดตอินสแตนซ์ที่ใช้งานอยู่ทั้งหมดของวิดเจ็ต ให้เรียกใช้ triggerUpdateAll ในคลาสวิดเจ็ต ดังนี้

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

หากต้องการอัปเดตอินสแตนซ์วิดเจ็ตที่เฉพาะเจาะจงโดยไม่ต้องรีเฟรชอินสแตนซ์ที่ใช้งานอยู่ทั้งหมด ให้เรียกใช้ triggerUpdate พร้อมรหัสอินสแตนซ์เป้าหมาย