Làm quen với các tiện ích

android skills add wear-widgets

Điều kiện tiên quyết và cách thiết lập

Trước khi bắt đầu, hãy đảm bảo môi trường của bạn đáp ứng các yêu cầu sau.

Yêu cầu về thời gian chạy

Tiện ích Wear yêu cầu phiên bản 1.6.1 trở lên của APK com.google.android.wearable.protolayout.renderer trên thiết bị mục tiêu.

Tải phiên bản tương thích của trình kết xuất theo một trong những cách sau:

• Trình mô phỏng Wear OS 7: Sử dụng hình ảnh trình mô phỏng Wear OS 7. Các phiên bản thấp hơn 7 không phù hợp. Để biết hướng dẫn thiết lập, hãy xem phần Thiết lập trình mô phỏng Wear OS 7.
• Thiết bị thực: Sử dụng thiết bị Wear OS thực nhận được bản cập nhật tự động từ Cửa hàng Google Play hoặc thiết bị của nhà phát triển đã đăng nhập vào Cửa hàng Google Play.

Để kiểm tra phiên bản bạn đã cài đặt trên thiết bị, hãy sử dụng lệnh sau:

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

Cấu hình Gradle

Thư viện Tiện ích cho Wear có trên Google Maven.

1. Định cấu hình phiên bản SDK

Đảm bảo compileSdk và targetSdk của bạn được đặt thành 37 trở lên.

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

2. Thêm phần phụ thuộc

Thêm các phần phụ thuộc sau vào tệp build.gradle.kts của ứng dụng:

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

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

Tạo tiện ích Hello World

Tiện ích Wear bao gồm một dịch vụ mở rộng GlanceWearWidgetService và một lớp tiện ích mở rộng GlanceWearWidget. Bạn xác định giao diện người dùng bằng các hàm @RemoteComposable.

Xác định dịch vụ

Dịch vụ là điểm truy cập mà hệ thống liên kết đến.

Để xác định tiện ích, hãy tạo một dịch vụ mở rộng GlanceWearWidgetService và chú thích dịch vụ đó bằng @AssociateWithGlanceWearWidget để liên kết dịch vụ với lớp GlanceWearWidget thích hợp.

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

Xác định tiện ích

Lớp tiện ích cung cấp dữ liệu và bố cục cho tiện ích.

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

Xác định nội dung

Nội dung được tạo bằng các thành phần Remote Compose.

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

Xem trước tiện ích trong Android Studio

Bạn có thể xem trước bố cục tiện ích ngay trong bảng điều khiển Design (Thiết kế) của Android Studio bằng cách sử dụng androidx.glance.wear:wear-tooling-preview.

Bộ xem trước được xác định trước

Thư viện wear-tooling-preview cung cấp các bộ PreviewParameterProvider được xác định trước để kiểm thử bố cục trên nhiều hình dạng vùng chứa và cấu hình thiết bị:

• Squircle Suite (SquircleAllWidgetPreviewParams): Vùng chứa hình chữ nhật bo tròn.
• Bộ biểu tượng tròn (RoundAllWidgetPreviewParams): Vùng chứa hình viên thuốc.
• Bộ hình chữ nhật (RectangularAllWidgetPreviewParams): Vùng chứa hình chữ nhật không bị cắt, có khoảng đệm an toàn. Hình ảnh được tạo bằng cấu hình xem trước này phù hợp để dùng làm hình ảnh xem trước được nhúng trong APK mà bộ chọn tiện ích sử dụng (xem phần Tạo thành phần hình ảnh xem trước).

Để xem trước tiện ích trong Android Studio, hãy sử dụng @WearWidgetPreview:

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

Tạo tệp XML cấu hình tiện ích

Tạo một tệp res/xml/hello_widget_info.xml mới để xác định các thuộc tính và kích thước được hỗ trợ của tiện ích. Để xem tài liệu tham khảo đầy đủ về các thuộc tính XML được hỗ trợ trong thẻ <wearwidget-provider>, hãy xem tài liệu về 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

Tạo thành phần hình ảnh xem trước

Thuộc tính previewImage của phần tử <container> tham chiếu đến một thành phần có thể vẽ xuất hiện trong bộ chọn tiện ích hệ thống. Để tạo tài sản để xem trước có ranh giới và mật độ chính xác, hãy sử dụng Bản xem trước Android Studio với RectangularAllWidgetPreviewParams (tạo các biến thể xem trước cho cả vùng chứa nhỏ và lớn) và chỉ định mật độ hiển thị của đồng hồ thông minh là 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

Để trích xuất hình ảnh xem trước được kết xuất, hãy hoàn tất các bước sau:

1. Trong Android Studio, hãy mở nền tảng Design (Thiết kế) cho thành phần kết hợp xem trước.
2. Trong cửa sổ xem trước, hãy nhấp chuột phải vào bản xem trước được kết xuất hoặc sử dụng thanh công cụ xem trước để chọn Copy Image (Sao chép hình ảnh) hoặc lưu hình ảnh. Ngoài ra, bạn có thể sử dụng công cụ CLI hoặc tập lệnh tự động để trích xuất bản xem trước trong Compose.
3. Lưu các tệp hình ảnh nhỏ và lớn vào thư mục res/drawable-nodpi/ của ứng dụng, chẳng hạn như res/drawable-nodpi/widget_preview_small.png và res/drawable-nodpi/widget_preview_large.png.

Đăng ký trong AndroidManifest.xml

Đăng ký dịch vụ trong AndroidManifest.xml bằng các bộ lọc ý định và siêu dữ liệu bắt buộc.

<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

Xây dựng và triển khai

Sau khi xác định dịch vụ và tiện ích, bạn có thể tạo dự án và triển khai dự án đó cho một thiết bị hoặc trình mô phỏng.

Xây dựng và cài đặt

Tạo bản dựng dự án và cài đặt tệp APK gỡ lỗi vào thiết bị thông minh hoặc trình mô phỏng đã kết nối:

./gradlew :app:installDebug

Thêm và xem trước tiện ích

Sau khi cài đặt ứng dụng, hãy sử dụng adb để thêm tiện ích vào băng chuyền theo cách lập trình và hiển thị tiện ích đó trên màn hình.

Lưu ý: Tiện ích Wear sử dụng cơ sở hạ tầng thẻ thông tin cơ bản cho mục đích gỡ lỗi. Do đó, các lệnh adb yêu cầu các thao tác add-tile và show-tile.

1. Thêm tiện ích vào băng chuyền:

adb shell am broadcast \
  -a com.google.android.wearable.app.DEBUG_SURFACE \
  --es operation add-tile \
  --ecn component <your_package_name>/.HelloWidgetService

2. Hiển thị tiện ích:

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

Cập nhật nội dung tiện ích theo phương thức lập trình

Khi dữ liệu cơ bản của ứng dụng thay đổi (chẳng hạn như nhận được thông báo đẩy, đồng bộ hoá dữ liệu hoặc hành động của người dùng), hãy thông báo cho hệ thống để làm mới nội dung tiện ích.

Để yêu cầu cập nhật cho tất cả các thực thể đang hoạt động của tiện ích, hãy gọi triggerUpdateAll trên lớp tiện ích:

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

Để cập nhật một thực thể tiện ích cụ thể mà không cần làm mới tất cả thực thể đang hoạt động, hãy gọi triggerUpdate bằng mã thực thể mục tiêu.