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

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

Lấy 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 bài viết Thiết lập trình mô phỏng Wear OS 7.
  • Thiết bị thực: Sử dụng một thiết bị Wear OS thực nhận được các bản cập nhật tự động từ Cửa hàng Google Play hoặc một thiết bị dành cho 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 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 Wear có trên Google Maven.

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

Đảm bảo bạn đã đặt compileSdk và targetSdk 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:

Groovy

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

Kotlin

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

Xây dựng 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ụ này 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()
}

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

Xác định nội dung

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

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

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 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 của bạn trên nhiều hình dạng vùng chứa và cấu hình thiết bị:

  • Squircle Suite (SquircleAllWidgetPreviewParams): Các vùng chứa hình chữ nhật bo tròn.
  • Round Suite (RoundAllWidgetPreviewParams): Vùng chứa có hình viên thuốc.
  • Rectangular Suite (RectangularAllWidgetPreviewParams): Các vùng chứa hình chữ nhật chưa được 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à trình chọn tiện ích 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,
    )
}

Tạo 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. Để biết thông tin 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 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>

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 công cụ chọn tiện ích hệ thống. Để tạo các thành phần xem trước có ranh giới và mật độ chính xác, hãy sử dụng Android Studio Previews 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 độ màn hình đồ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,
    )
}

Để 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ở giao diện 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 đã hiển thị hoặc sử dụng thanh công cụ xem trước để chọn Sao chép hình ảnh hoặc lưu hình ảnh. Ngoài ra, hãy sử dụng công cụ CLI hoặc tập lệnh tự động để trích xuất bản xem trước 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>

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 dự án và cài đặt APK gỡ lỗi vào thiết bị 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 dùng adb để thêm tiện ích vào băng chuyền theo phương thức 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 cơ bản của ô 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 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 đồng bộ hoá dữ liệu, thông báo đẩy 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 của tiện ích.

Để yêu cầu cập nhật cho tất cả các phiên bản đ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 phiên bản tiện ích cụ thể mà không cần làm mới tất cả các phiên bản đang hoạt động, hãy gọi triggerUpdate bằng mã nhận dạng phiên bản mục tiêu.