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

Lưu ý: Hướng dẫn này giả định rằng bạn đang tạo một tiện ích mới và chưa có ô nào. Nếu bạn đang cập nhật một ứng dụng đã có một ô hiện có, hãy đọc hướng dẫn Di chuyển từ ô sang tiện ích để định cấu hình các dịch vụ của bạn.

Đ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 một phiên bản trình kết xuất tương thích 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-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")
}

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. Giao diện người dùng được xác định bằng các hàm @RemoteComposable. 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ì thư viện này đang trong quá trình phát triển nên một số API bị hạn chế trong khi tên và cấu trúc cuối cùng của chúng đang được hoàn thiện. Việc sử dụng chú thích @SuppressLint("RestrictedApi") sẽ cho trình biên dịch biết rằng bạn đang cố ý sử dụng những tính năng mới và đang phát triển này. Yêu cầu này là tạm thời và sẽ bị xoá sau khi các API được hoàn thiện trong một bản phát hành ổn định sau này.

@SuppressLint("RestrictedApi")
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.

@SuppressLint("RestrictedApi")
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.

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

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>
hello_widget_info.xml

Đă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 dự án và cài đặt 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 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 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

Lưu ý: Lệnh bên trên sẽ thêm một ô toàn màn hình theo mặc định. Bạn cũng có thể chỉ định kích thước LỚN và NHỎ bằng cách truyền --ei type [0|1|2] vào lệnh (trong đó loại 0 là TOÀN MÀN HÌNH).

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

Android Studio Previews cũng có sẵn để giúp bạn kiểm thử bố cục trên nhiều kích thước màn hình.