Tạo phiên bản cho thẻ thông tin

Trên thiết bị Wear OS, thẻ thông tin được hiển thị bằng hai thành phần chính có phiên bản độc lập. Để đảm bảo thẻ thông tin ứng dụng hoạt động chính xác trên tất cả thiết bị, bạn cần hiểu rõ cấu trúc cơ bản này.

  • Thư viện liên quan đến thẻ thông tin Jetpack: Các thư viện này (bao gồm cả Thẻ thông tin Wear và Wear ProtoLayout) được nhúng trong ứng dụng của bạn và bạn (với tư cách là nhà phát triển) sẽ kiểm soát các phiên bản của chúng. Ứng dụng của bạn sử dụng các thư viện này để tạo đối tượng TileBuilder.Tile (cấu trúc dữ liệu đại diện cho Thẻ thông tin) để phản hồi lệnh gọi onTileRequest() của hệ thống.
  • Trình kết xuất ProtoLayout: Thành phần hệ thống này chịu trách nhiệm kết xuất đối tượng Tile trên màn hình và xử lý các hoạt động tương tác của người dùng. Phiên bản trình kết xuất không do nhà phát triển ứng dụng kiểm soát và có thể khác nhau giữa các thiết bị, ngay cả những thiết bị có phần cứng giống hệt nhau.

Giao diện hoặc hành vi của Thẻ thông tin có thể khác nhau tuỳ thuộc vào cả phiên bản thư viện Thẻ thông tin Jetpack của ứng dụng và phiên bản Trình kết xuất bố cục nguyên mẫu trên thiết bị của người dùng. Ví dụ: một thiết bị có thể hỗ trợ tính năng xoay hoặc hiển thị dữ liệu nhịp tim, còn thiết bị khác thì không.

Tài liệu này giải thích cách đảm bảo ứng dụng của bạn tương thích với các phiên bản khác nhau của thư viện Thẻ thông tin và Trình kết xuất ProtoLayout, cũng như cách di chuyển sang các phiên bản thư viện Jetpack cao hơn.

Cân nhắc khả năng tương thích

Để tạo Thẻ thông tin hoạt động chính xác trên nhiều thiết bị, bạn nên cân nhắc những điều sau.

Phát hiện phiên bản trình kết xuất

  • Sử dụng phương thức getRendererSchemaVersion() của đối tượng DeviceParameters được truyền vào phương thức onTileRequest(). Phương thức này trả về số phiên bản chính và phụ của Trình kết xuất ProtoLayout trên thiết bị.
  • Sau đó, bạn có thể sử dụng logic có điều kiện trong quá trình triển khai onTileRequest() để điều chỉnh thiết kế hoặc hành vi của Thẻ thông tin dựa trên phiên bản trình kết xuất được phát hiện.
    • Ví dụ: nếu một ảnh động cụ thể không được hỗ trợ, bạn có thể hiển thị một hình ảnh tĩnh.

Chú thích @RequiresSchemaVersion

  • Chú thích @RequiresSchemaVersion trên các phương thức ProtoLayout cho biết phiên bản giản đồ trình kết xuất tối thiểu cần thiết để phương thức đó hoạt động như đã ghi nhận (ví dụ).
    • Mặc dù việc gọi một phương thức yêu cầu phiên bản trình kết xuất cao hơn phiên bản có trên thiết bị sẽ không khiến ứng dụng của bạn gặp sự cố, nhưng điều này có thể dẫn đến việc nội dung không hiển thị hoặc tính năng bị bỏ qua.

Ví dụ

override fun onTileRequest(
    requestParams: TileService.TileRequest
): ListenableFuture<Tile> {
    val rendererVersion =
        requestParams.deviceConfiguration.rendererSchemaVersion
    val tile = Tile.Builder()

    if (
        rendererVersion.major > 1 ||
            (rendererVersion.major == 1 && rendererVersion.minor >= 300)
    ) {
        // Use a feature supported in renderer version 1.300 or later
        tile.setTileTimeline(/* ... */ )
    } else {
        // Provide fallback content for older renderers
        tile.setTileTimeline(/* ... */ )
    }

    return Futures.immediateFuture(tile.build())
}

Kiểm thử với nhiều phiên bản trình kết xuất

Để kiểm thử thẻ thông tin của bạn với các phiên bản trình kết xuất khác nhau, hãy triển khai các thẻ thông tin đó cho các phiên bản trình mô phỏng Wear OS khác nhau. (Trên thiết bị thực, các bản cập nhật Trình kết xuất ProtoLayout sẽ do Cửa hàng Play hoặc bản cập nhật hệ thống phân phối. Không thể buộc cài đặt một phiên bản trình kết xuất cụ thể.)

Tính năng Xem trước thẻ thông tin của Android Studio sử dụng trình kết xuất được nhúng trong thư viện Jetpack ProtoLayout mà mã của bạn phụ thuộc vào. Vì vậy, một phương pháp khác là phụ thuộc vào các phiên bản thư viện Jetpack khác nhau khi kiểm thử thẻ thông tin.

Nâng cấp thư viện Jetpack

Cập nhật thư viện Thẻ thông tin Jetpack để tận dụng các tính năng nâng cao mới nhất, bao gồm cả các thay đổi về giao diện người dùng để Thẻ thông tin của bạn tích hợp liền mạch với hệ thống.

Di chuyển sang Thẻ thông tin 1.2 / ProtoLayout 1.0

Kể từ phiên bản 1.2, hầu hết các API Bố cục thẻ thông tin đều nằm trong không gian tên androidx.wear.protolayout. Để sử dụng các API mới nhất, hãy hoàn tất các bước di chuyển sau đây trong mã của bạn.

Cập nhật phần phụ thuộc

Trong tệp bản dựng của mô-đun ứng dụng, hãy thực hiện các thay đổi sau:

Groovy

  // Remove
  implementation 'androidx.wear.tiles:tiles-material:version'

  // Include additional dependencies
  implementation "androidx.wear.protolayout:protolayout:1.2.1"
  implementation "androidx.wear.protolayout:protolayout-material:1.2.1"
  implementation "androidx.wear.protolayout:protolayout-expression:1.2.1"

  // Update
  implementation "androidx.wear.tiles:tiles:1.4.1"

Kotlin

  // Remove
  implementation("androidx.wear.tiles:tiles-material:version")

  // Include additional dependencies
  implementation("androidx.wear.protolayout:protolayout:1.2.1")
  implementation("androidx.wear.protolayout:protolayout-material:1.2.1")
  implementation("androidx.wear.protolayout:protolayout-expression:1.2.1")

  // Update
  implementation("androidx.wear.tiles:tiles:1.4.1")

Cập nhật không gian tên

Trong các tệp mã dựa trên Kotlin và Java của ứng dụng, hãy cập nhật như sau. Ngoài ra, bạn có thể thực thi tập lệnh đổi tên không gian tên này.

  1. Thay thế tất cả các lệnh nhập androidx.wear.tiles.material.* bằng androidx.wear.protolayout.material.*. Bạn cũng cần hoàn tất bước này cho thư viện androidx.wear.tiles.material.layouts.

  2. Thay thế hầu hết các lệnh nhập androidx.wear.tiles.* khác bằng androidx.wear.protolayout.*.

    Các lệnh nhập cho androidx.wear.tiles.EventBuilders, androidx.wear.tiles.RequestBuilders, androidx.wear.tiles.TileBuilders và androidx.wear.tiles.TileService sẽ giữ nguyên.

  3. Đổi tên một vài phương thức không dùng nữa trong các lớp TileService và TileBuilder:

    1. TileBuilders: getTimeline() thành getTileTimeline() và setTimeline() thành setTileTimeline()
    2. TileService: onResourcesRequest() thành onTileResourcesRequest()
    3. RequestBuilders.TileRequest: getDeviceParameters() thành getDeviceConfiguration(), setDeviceParameters() thành setDeviceConfiguration(), getState() thành getCurrentState() và setState() thành setCurrentState()