在 Compose 中將 XML 主題遷移至 Material 3

在現有應用程式中導入 Compose 時，必須遷移 Material XML 主題，才能在 Compose 元件中使用 MaterialTheme。這表示應用程式的主題設計將有兩個可靠資料來源：以 View 為基礎的主題和 Compose 主題。如要進行樣式變更，您必須在多個位置進行。應用程式完全遷移至 Compose 後，請移除 XML 主題。

您可以使用 Material Design 主題設定建構工具遷移顏色。

從 XML 遷移至 Compose 時，請將主題設定遷移至 Material 3 Compose 主題設定。

詞彙解釋

字詞	定義
MaterialTheme	可組合函式，可為 Compose UI 元件提供主題 (顏色、字體排版、形狀)。
Shape	用於定義 MaterialTheme 自訂元件形狀的 Compose 物件。
Typography	用於定義 MaterialTheme 自訂文字樣式 (字型系列、大小、粗細) 的 Compose 物件。
Color	用於定義 MaterialTheme 自訂色彩配置的 Compose 物件。
XML 主題	Android 主題系統定義於 XML 檔案中，供 View 系統使用。

限制

遷移前請注意下列限制：

• 本指南僅著重於遷移至 Material 3。如要從其他設計系統遷移，請參閱「Material 2」或「Compose 中的自訂設計系統」。
• 最終目標是完全遷移至 Compose，這樣就能移除 XML 主題設定。本指南說明如何遷移，但未說明如何最終移除 XML 主題設定。

步驟 1：評估設計系統

找出 XML 檢視專案中使用的設計系統。 分析遷移路徑和必要步驟，將現有設計系統遷移至 Compose 中的 Material 3。

步驟 2：找出主題來源檔案

找出並定位主題設定所需的所有 XML 資源和檔案：淺色和深色配色、主題、形狀、尺寸、排版、樣式和其他相關檔案。

字串等資源可直接重複使用，無須遷移。

步驟 3：遷移顏色

將 XML 中的深色和淺色色彩配置，遷移至 Material 3 Compose 中的對應項目。

注意： Material 3 的命名方式與 Material 2 的顏色命名方式不同。

步驟 4：遷移自訂形狀和字體排版

• 如果應用程式使用自訂形狀：

  1. 在 Compose 程式碼中，定義 Shape 物件來複製 XML 形狀定義。

  2. 將這個 Shape 物件提供給 MaterialTheme。

     詳情請參閱「形狀」。

• 如果應用程式使用自訂字體排版：

  1. 在 Compose 程式碼中定義 Typography 物件，複製 XML 文字樣式和字型定義。

  2. 將這個 Typography 物件提供給 MaterialTheme。

     詳情請參閱「字體排版」。

步驟 5：驗證主題遷移作業

一律使用原始 XML 主題的現有主題值，做為 Compose 中新版 Material 主題的單一事實來源。遷移期間請勿建立新的主題值，以免品牌風格不一致，並避免視覺效果回歸。

確認所有新的 Compose 主題值都與現有的 XML 值相符。 請勿將任何遷移的值硬式編碼。