從動態磚遷移至小工具

雖然動態磚和小工具都會在遠端系統介面上顯示內容，但兩者的建構方式不同。將現有動態磚遷移至小工具，表示要從嚴格的版面配置生成作業，轉換為動態的宣告式 UI，解鎖新功能並簡化開發模式。

選擇導入策略

如果您要遷移的應用程式會維護舊版動態磚，請務必決定應用程式要如何向系統提供內容。全新小工具應使用單一小工具服務，但現有動態磚的應用程式必須選擇維持兩種服務，或整合為單一小工具服務。

建議：雙重服務 (動態磚 + 小工具)

如果應用程式已有動態磚，建議同時維護動態磚和 Widget。提供兩種不同的服務，可讓使用者在不同裝置上獲得最佳體驗。

雙服務設定的系統行為：

作業系統 / 裝置功能 結果體驗
Wear OS 3 使用 Tile
Wear OS 4、5、6 使用 Tile
Wear OS 7 (不支援部分高度，例如 Pixel Watch) 使用 Tile
Wear OS 7 (支援部分高度，例如 Galaxy Watch) 使用小工具

替代方案：單一服務 (僅限小工具)

單一服務會同時處理這兩種通訊協定。雖然這種做法的實作速度較快，但必須透過相容模式，才能在執行較舊版 Wear OS 的裝置上，將小工具「改編」為動態磚。

如果選擇這個方法：

  1. 指定兩個意圖篩選器：服務必須包含 androidx.wear.tiles.action.BIND_TILE_PROVIDER 和 androidx.glance.wear.action.BIND_WIDGET_PROVIDER 的意圖篩選器。確保小工具顯示在 Wear 4、5、6 和 7 的動態磚介面 (如適用)。
  2. 保留現有的服務名稱 (確保升級過程順暢)：如果您要取代現有的動態磚，請保留相同的服務類別名稱，這樣一來，輪播介面中的動態磚就會自動更新為新小工具。Wear OS 7 會在小工具設定 XML 中使用 group 屬性，從邏輯上連結不同元件，但 Wear OS 7 以下版本會依據服務名稱，將元件識別為「相同」。如果偏好使用新服務名稱，應用程式仍可正常運作，但執行 Wear OS 第 6 版或更舊版本的使用者，必須手動將小工具重新加入輪播畫面。

單一服務設定的系統行為：

作業系統 / 裝置功能 結果體驗
Wear OS 3 不支援
Wear OS 4、5、6 小工具顯示為全螢幕動態磚
Wear OS 7 (不支援部分高度) 小工具轉換為動態磚
Wear OS 7 (支援部分高度) 使用小工具

*須使用 1.6 以上版本的算繪器。

UI 翻譯訣竅

將 UI 從 ProtoLayout (資訊方塊) 轉換為 Remote Compose (小工具) 時，心智模型會從命令式版面配置建構工具，轉移至以 Compose 為基礎的狀態驅動式架構，UI 更新會透過重新組合處理。請謹記下列原則：

  • 採用宣告式 UI：以宣告式 Remote Compose 對等項目 (例如 RemoteText、RemoteColumn 和 RemoteBox)，取代命令式 ProtoLayout 建構工具 (LayoutElementBuilders)。
  • 著重於核心內容 (mainSlot)：部分高度的小工具 (例如 SMALL 和 LARGE 容器類型) 提供可一目瞭然的聚焦介面。請勿直接移植密集的全螢幕動態磚版面配置，而是簡化設計，強調主要內容區域中的主要資訊。
  • 重新設計邊緣對齊動作：在動態磚架構中，EdgeButton 等緊貼螢幕的元件會錨定至專屬的 bottomSlot。由於部分高度的小工具會直接整合到垂直捲動介面中，因此不再有固定 bottomSlot 範例。由於邊緣對齊的按鈕通常是顯眼的主要動作，因此遷移時需要重新設計 UI，而不是直接替換元件。評估主要動作的替代使用者體驗策略：
    • 內嵌動作：直接在 mainSlot 版面配置中整合內嵌 RemoteButton。
    • 容器輕觸：使用 PendingIntentAction 讓整個小工具容器可供輕觸，整合互動。
    • 內容走向改變：重新評估小工具的重點。如果沒有專屬動作位置，請考慮顯示更豐富的瀏覽資料，並透過單次輕觸開啟完整應用程式，而非在小工具介面上隔離特定動作。
  • 遷移事件處理 (動作與 Lambda)：圖塊會依賴互動 (例如 LoadAction) 觸發完整服務回呼，以重新整理 UI。Wear 小工具是由用戶端驅動，標準 Compose lambda 無法遠端執行，請改為提供可序列化的宣告式動作 (例如 ValueChange 或 PendingIntentAction)。將這些動作與宣告式狀態 (例如 rememberMutableRemoteInt) 結合，即可支援即時 UI 更新，不必往返應用程式。
  • 調整尺寸和類型：遷移版面配置尺寸時，請優先使用 RemoteDp (例如 10.rdp) 進行延遲版面配置解析，而非標準的 Dp。這可確保系統算繪器在顯示時正確計算像素值。同樣地，使用 Remote Compose 擴充功能函式 (.rc 適用於 Color、.rs 適用於 String、.rdp 適用於 Dp)，即可順暢轉換標準 Kotlin 和 Remote Compose 型別。
  • 查看程式碼範例：如要查看如何建構版面配置、套用語意字型樣式，以及在 Remote Compose 中管理狀態的完整範例，請瀏覽 Wear OS 範例存放區中的官方程式碼範例。