資訊方塊版本管理

在 Wear OS 裝置上，資訊方塊會由兩個具有獨立版本的關鍵元件轉譯。如要確保應用程式資訊方塊可在所有裝置上正常運作，請務必瞭解這個基礎架構。

  • Jetpack 資訊方塊相關程式庫：這些程式庫 (包括 Wear 資訊方塊和 Wear ProtoLayout) 會嵌入應用程式，而您身為開發人員，可控制其版本。應用程式會使用這些程式庫，在回應系統的 onTileRequest() 呼叫時，建構 TileBuilder.Tile 物件 (代表資訊方塊的資料結構)。
  • ProtoLayout 轉譯器：這個系統元件負責在螢幕上轉譯 Tile 物件，並處理使用者互動。轉譯器的版本並非由應用程式開發人員控制，且可能因裝置而異，即使是硬體相同的裝置也不例外。

資訊方塊的外觀或行為可能會因應用程式的 Jetpack Tiles 程式庫版本，以及使用者裝置上的 ProtoLayout 轉譯器版本而異。舉例來說，某台裝置可能支援旋轉或顯示心率資料，而另一台裝置則不支援。

本文件說明如何確保應用程式與不同版本的磁磚程式庫和 ProtoLayout 轉譯器相容，以及如何遷移至較新的 Jetpack 程式庫版本。

考量相容性

如要建立可在多種裝置上正常運作的方塊，請考慮下列事項。

偵測轉譯器版本

  • 使用傳遞至 onTileRequest() 方法的 DeviceParameters 物件 getRendererSchemaVersion() 方法。這個方法會傳回裝置上 ProtoLayout 轉譯器的主要和次要版本號碼。
  • 接著，您可以在 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 轉譯器更新會透過 Play 商店或系統更新提供。您無法強制安裝特定轉譯器版本。)

Android Studio 的資訊方塊預覽功能會使用程式碼所依附的 Jetpack ProtoLayout 程式庫中嵌入的轉譯器，因此另一種做法是在測試資訊方塊時，依附不同的 Jetpack 程式庫版本。

升級 Jetpack 程式庫

更新 Jetpack 資訊方塊程式庫，充分運用最新增強功能，包括 UI 變更，讓資訊方塊與系統完美整合。

遷移至 Tiles 1.2 / ProtoLayout 1.0

自 1.2 版起，大多數的資訊方塊版面配置 API 都位於 androidx.wear.protolayout 命名空間中。如要使用最新的 API，請完成下列程式碼遷移步驟。

更新依附元件

在應用程式模組的建構檔案中進行下列變更：

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