功能块版本控制

在 Wear OS 设备上，功能块由两个具有独立版本控制的关键组件呈现。为了确保您的应用功能块在所有设备上正常运行，请务必了解此底层架构。

  • 与 Jetpack 功能块相关的库：这些库（包括 Wear 功能块和 Wear ProtoLayout）会嵌入到您的应用中，并且您（作为开发者）可以控制其版本。您的应用会使用这些库来构建 TileBuilder.Tile 对象（表示功能块的数据结构），以响应系统的 onTileRequest() 调用。
  • ProtoLayout 渲染程序：此系统组件负责在显示屏上渲染 Tile 对象并处理用户互动。渲染程序的版本不受应用开发者控制，并且可能会因设备而异，即使是硬件相同的设备也是如此。

功能块的外观或行为可能会因应用的 Jetpack Tiles 库版本以及用户设备上的 ProtoLayout Renderer 版本而异。例如，一台设备可能支持旋转或显示心率数据，而另一台设备可能不支持。

本文档介绍了如何确保您的应用与不同版本的功能块库和 ProtoLayout 渲染程序兼容，以及如何迁移到更高版本的 Jetpack 库。

考虑兼容性

若要创建在各种设备上都能正常运行的功能块，您应考虑以下事项。

检测渲染程序版本

  • 使用传递给 onTileRequest() 方法的 DeviceParameters 对象的 getRendererSchemaVersion() 方法。此方法会返回设备上 ProtoLayout Renderer 的主要版本号和次要版本号。
  • 然后，您可以在 onTileRequest() 实现中使用条件逻辑，根据检测到的渲染程序版本调整功能块的设计或行为。
    • 例如，如果系统不支持特定动画，您可以改为显示静态图片。

@RequiresSchemaVersion 注解

  • ProtoLayout 方法上的 @RequiresSchemaVersion 注解表示使该方法按文档中所述的方式运行所需的最小渲染程序架构版本（示例）。
    • 虽然调用需要高于设备上可用版本的渲染程序版本的方法不会导致应用崩溃，但可能会导致内容无法显示或系统忽略相应功能。

示例

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

使用不同的渲染程序版本进行测试

如需针对不同的渲染程序版本测试功能块，请将其部署到不同版本的 Wear OS 模拟器。（在实体设备上，ProtoLayout Renderer 更新由 Play 商店或系统更新提供。无法强制安装特定的渲染程序版本。）

Android Studio 的功能块预览功能会使用嵌入在代码依赖的 Jetpack ProtoLayout 库中的渲染程序，因此另一种方法是在测试功能块时依赖于不同的 Jetpack 库版本。

升级 Jetpack 库

更新您的 Jetpack 功能块库，以利用最新的增强功能，包括界面更改，以便功能块与系统无缝集成。

迁移到功能块 1.2 / ProtoLayout 1.0

从版本 1.2 开始，大多数功能块布局 API 都位于 androidx.wear.protolayout 命名空间中。如需使用最新的 API，请在代码中完成以下迁移步骤。

更新依赖项

在应用模块的 build 文件中，进行以下更改：

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

更新命名空间

在应用的 Kotlin 和 Java 代码文件中，进行以下更新。或者，您也可以执行此命名空间重命名脚本。

  1. 将所有 androidx.wear.tiles.material.* 导入内容都替换为 androidx.wear.protolayout.material.*。另外也针对 androidx.wear.tiles.material.layouts 库完成此步骤。

  2. 将大多数其他 androidx.wear.tiles.* 导入内容替换为 androidx.wear.protolayout.*。

    androidx.wear.tiles.EventBuilders、androidx.wear.tiles.RequestBuilders、androidx.wear.tiles.TileBuilders 和 androidx.wear.tiles.TileService 的导入内容应保持不变。

  3. 重命名 TileService 和 TileBuilder 类中的一些已废弃的方法：

    1. TileBuilders：将 getTimeline() 重命名为 getTileTimeline()，将 setTimeline() 重命名为 setTileTimeline()
    2. TileService：将 onResourcesRequest() 重命名为 onTileResourcesRequest()
    3. RequestBuilders.TileRequest：将 getDeviceParameters() 重命名为 getDeviceConfiguration()，将 setDeviceParameters() 重命名为 setDeviceConfiguration()，将 getState() 重命名为 getCurrentState()，将 setState() 重命名为 setCurrentState()