遠端 Compose 概念和架構

Remote Compose 是 Jetpack 程式庫，可讓您在應用程式中使用 Compose 樣式的 API 建構 UI，並在系統程序中顯示，例如應用程式小工具或 Wear OS 小工具。應用程式會將 UI 記錄為精簡文件，主機程序中的播放器會在本機轉譯 UI 並處理互動、狀態變更和動畫，而不會回呼應用程式。

本指南說明遠端 Compose 架構，以及與標準 Jetpack Compose 的差異。本指南著重於使用元件建構 UI。

遠端 Compose 用途

只要有支援的播放器，就能在任何介面上使用遠端 Compose。在 Android 上，Glance 可用於建構應用程式小工具和 Wear OS 小工具。

運作方式：三區塊架構

Remote Compose 與標準 Jetpack Compose 的基本架構差異，在於將 UI 定義與執行作業分離，分為三個高階區塊：

• 建立文件：應用程式會執行 @RemoteComposable 函式來記錄文件，也就是精簡、序列化的 UI 說明，包括版面配置、遠端狀態和動作。資料變更時，應用程式可以記錄並傳送新文件。
• 將文件傳輸至遠端主機：應用程式會將文件傳遞至主機，也就是顯示文件的程序，例如啟動器或 Wear OS。
• 播放文件：主機中的遠端 Compose 播放器會在本機轉譯文件，並處理版面配置、輸入、使用者體驗狀態變更和動畫，而不會回呼應用程式。

這種架構的主要優點是能直接降低延遲：

• 文件大小小：序列化文件快照仍保持精簡輕巧。
• 減少來回：由於遠端主機播放器會在本地處理互動和狀態變更，因此可大幅減少與應用程式或伺服器的來回通訊。

網頁/HTML 類比：遠端 Compose 的運作方式與提供網頁類似。應用程式伺服器會生成並傳送 HTML/文件結構一次，瀏覽器主機則會在本機轉譯並處理互動，不必持續查詢後端。

元件

Remote Compose 提供高階 UI 元件，可用於建構版面配置。請使用遠端 Compose 元件和 RemoteModifier，而非標準 Compose 對等項目。包括基本版面配置容器，以及專為處理動態螢幕大小而設計的自動調整元件：

• 基本版面配置元件：常見的 Compose 樣式版面配置元素，例如 RemoteBox、RemoteRow 和 RemoteColumn。
• 自動調整版面配置元件：RemoteFitBox、RemoteCollapsibleRow 和 RemoteCollapsibleColumn 等專用元件，可自動調整以在遠端介面上清楚顯示。
• Material Design 主題設定：主題設定在 Wear OS 小工具中的運作方式相同，由 RemoteMaterialTheme 提供顏色和字體排版階層。這樣一來，應用程式和小工具就能採用一致的品牌宣傳和設計系統。

使用 RemoteCanvas 自訂繪圖

如要自訂圖形和時間型動畫，請使用 RemoteCanvas，記錄播放器在主機上執行的繪圖指令。本指南著重於使用元件建構 UI。

主要差異

請詳閱下列核心概念，瞭解 Remote Compose 如何管理狀態、邏輯和動作。

符號狀態參照

在標準 Compose 中，狀態容器會將可讀取的主動值，保存在應用程式本機記憶體中，並在事件發生時由應用程式程式碼 (lambda) 變動。在遠端 Compose 中，狀態宣告會做為符號參照。這些元件不會將有效值保留在本機應用程式記憶體中，而是宣告繫結，由遠端播放器在執行階段管理及更新本機。在遠端 Compose 中宣告狀態時，請注意下列事項：

• 使用 Remote Compose 工廠函式宣告狀態，例如 rememberMutableRemoteInt、rememberMutableRemoteFloat 或 rememberMutableRemoteString。
• 應用程式程式碼無法在組合期間直接檢查或讀取遠端狀態變數的值。
• 當使用者與文件互動時，播放器會在本機儲存及更新這些值。

遠端狀態與 Kotlin 控制流程

只有在應用程式建立文件時，系統才會執行 Kotlin 程式碼。Kotlin 陳述式 (例如 if、when 和 for) 可根據當時已知的值來塑造文件，例如為清單中的每個項目重複一個資料列，但無法對稍後變更的遠端狀態做出反應。使用遠端撰寫功能時，請注意下列事項：

• 分支邏輯：動態 UI 切換是使用 RemoteStateLayout，將狀態對應至不同的 RemoteComposable 插槽。
• 文字評估：避免使用標準 Kotlin 字串內插 ("$remoteValue")，因為這只會在建立文件時進行評估。請改為將 RemoteString 傳遞至 RemoteText。

使用 RemoteModifier 設定動態樣式

主機上的動態樣式不會重新執行組合，而是將遠端狀態變數直接傳遞至修飾符，例如 RemoteModifier.background(remoteColor)。

遠端系統情境

LocalConfiguration 或 LocalDensity 等 CompositionLocal 供應器，只會反映記錄文件時的本機應用程式環境。當介面調整大小、變更顯示狀態或時間推進時，遠端主機上的預覽畫面不會動態更新。請改用播放器在執行階段於主機上解析的值，例如元件的目前大小、RemoteConfiguration 或 RemoteDensity。

宣告式動作

在標準 Compose 中，點擊處理常式是在應用程式中執行的 lambda。主機無法執行應用程式的程式碼，因此在遠端 Compose 中，您需要改為附加動作，例如使用 RemoteModifier.clickable(action)。動作可以使用 valueChange 直接在主機上更新遠端狀態，也可以使用 pendingIntentAction 或 hostAction 將動作交給應用程式或主機。如要按一下就執行多項動作，請使用 combinedAction。

高階範式比較

特徵網域	標準 Jetpack Compose	Remote Compose
點擊和觸控事件	程序內同步 lambda	宣告式序列化 Action 物件
條件式邏輯	Kotlin if 和 when 控制流程	如果生成文件時已知靜態狀態，標準 Kotlin if/when 可正常運作。 動態分支使用 RemoteStateLayout (適用於 UI 樹狀結構)。
控制流程迴圈	標準 Kotlin for 和 while 迴圈	標準 Kotlin 迴圈 (repeat、for、forEach) 只會在建立文件時執行。無法在主機上循環執行遠端狀態
執行主機	應用程式程序	啟動器 (AppWidget)、Wear OS 小工具，或任何支援播放器的板型規格
程序生命週期	程序必須保持有效狀態，才能重新組成及算繪	處理記錄 UI 快照文件；遠端播放器引擎會剖析元件樹狀結構、追蹤狀態變動，並在本機重新繪製，不需回呼應用程式。
副作用	協同程式生命週期 (LaunchedEffect)	主機不支援。Composition 會在應用程式中執行以建立文件，因此協同程式效果無法驅動遠端 UI，除非整合功能保持 Composition 開啟。
狀態範式	本機記憶體狀態值	工廠函式 (rememberMutableRemoteInt()、rememberNamedRemoteColor())，會傳回符號狀態參照，而非原始值。