本頁面由 Cloud Translation API 翻譯而成。

將元件對應至現有程式碼

開發人員可提供 UI 套件和現有程式碼元件之間的對應關係，而不是產生的程式碼，藉此來自訂程式碼產生程序。當現有實作具有產生的程式碼無法實現的功能，例如動畫或複雜行為 (例如下拉式選單) 時，這種做法即可派上用場。

開發人員指定如何使用對應檔案來對應元件。對應檔案至少會說明程式碼產生器如何連結目標可組合函式，以便建立正確的用戶端程式碼。

對應元件總覽圖

範例如下：

在 Figma 中，設計人員會建立「Card」元件，其中包含執行個體/「Play Bar」元件，同時封裝兩個元件並傳送給開發人員。

當開發人員從 Figma 匯入 UI 套件時，系統會在 ui-packages 中建立 card 和 play_bar 目錄。建構專案時，會建立兩個可組合函式：Card 和 PlayBar。通常，因為「Card」包含 Figma 中的「Play Bar」執行個體，所以在程式碼中，Card 可組合函式包含對 PlayBar 可組合函式的呼叫。

然而，設計人員和開發人員希望 Card 改為使用現有的可組合項 MyExistingPlaybar，其具有在 Figma 中難以說明的功能。因此，開發人員新增名為 play_bar.json 的對應檔案，將 play_bar UI 套件對應至 MyExistingPlaybar：

{
    "target": "MyExistingPlaybar",
    "package": "com.example.myApp"
}

現在，當開發人員建構專案時，Card 會呼叫 MyExistingPlaybar，而非 PlayBar。請注意，MyExistingPlaybar 的參數必須與 PlayBar 相同 (但可以有一些差異，詳情請參閱下文的其他指令)。

對應檔案

在 Android Studio 專案中，會在 ui-packages 資料夾旁邊的 ui-package-resources/mappings 中新增對應檔案。Relay 會在建構期間尋找對應檔案。

專案檢視畫面中的對應檔案

產生對應檔案

Relay 可為任何匯入的 UI 套件產生對應檔案。請按照下列步驟操作：

在套件資料夾或目標 ui-package 資料夾中的任何檔案上按一下滑鼠右鍵。選取「產生對應檔案」。
在對話方塊中設定下列選項：
- 檔案位置：設定產生對應檔案的位置。
- 目標可組合函式：設定自訂可組合函式，以取代產生的可組合函式。您可以選擇使用現有的可組合項，或透過對話方塊建立新的可組合項。建立新的可組合項時，系統會建立與 UI 套件中定義相同參數的可組合項。
注意： 目標可組合項應以大寫字母開頭。
- 產生的檔案：設定對應檔案中的 generateImplementation 和 generatePreview 選項。詳情請參閱下方的「對應檔案內容」。
按一下「產生對應檔案」。系統會在 ui-package-resources/mapping 資料夾中建立新的對應檔案，並套用指定的設定。

您也可以按照下列步驟，從 Relay 套件模組 UI 開啟「Generate mapping file」對話方塊：

按一下目標 ui-package 資料夾內的任何 UI 套件檔案。
如果 Relay 工具視窗未自動開啟，請按一下 Relay 圖示來開啟視窗。
按一下「Package Options」下方的「Generate mapping file」按鈕。

注意： 如果所選 UI 套件有對應檔案，系統會改為顯示開啟檔案的連結。

對應檔案名稱

指定對應檔案的名稱必須與所取代元件的 UI 套件資料夾名稱相符。因此，play_bar.json 會將 ui-packages/mappings 資料夾中的 UI 套件對應至現有的程式碼元件。

對應檔案內容

對應檔案包含下列屬性：

target: (必要) 自訂可組合函式的名稱。根據預設，這是由產生的程式碼所建立的函式名稱。
```
"target" : "CustomComposableName"
```
package： (必填) 自訂可組合項所在的套件名稱。根據預設，這是由產生程式碼建立的函式套件。
```
"package" : "com.example.podcastapp.ui.components"
```
generateImplementation： (選用) true 或 false。如果為 True，系統仍會在產生的程式碼檔案中建立此 UI 套件的實作項目。如果為 false，就不會建立實作。根據預設，這個值為 true。
```
"generateImplementation" : true
```
generatePreviews： (選用) true 或 false。如果為 true，系統會在產生的程式碼檔案中建立對應自訂元件的預覽畫面。如果為 false，則不會建立預覽畫面。根據預設，這個值為 true。
```
"generatePreviews" : true
```

對應的變化版本

如果 Figma 元件包含變化版本，則產生的可組合項會包含用戶對變化版本編碼的列舉參數 (如處理設計變化版本教學課程中所述)。如果您想將含有變化版本的 Figma 元件對應至現有程式碼，則該元件必須對應至可組合項，且使用的參數與產生的可組合項參數相同。舉例來說，如果有一個名為 Chip 的 Figma 元件，其中變化版本的屬性為 ChipType，Chip 產生的可組合項簽名如下所示：

@Composable
fun Chip(
    modifier: Modifier = Modifier,
    chipType: ChipType = ChipType.Red,
    chipText: String
) { ... }

如果您想讓「Chip」Figma 元件對應至現有的 MyChip 可組合項，則 MyChip 的簽名必須與產生的可組合項相同 (假設沒有指定其他指令)。從概念上說，這意味著現有的程式碼元件能夠使用與 Figma 元件相同的設計變化版本。

其他指令

舉例來說，如果您要指定的可組合函式具有下列簽名：

@Composable
fun MyChip(
    modifier: Modifier = Modifier,
    chipType: ChipType = ChipType.Red,
    description: String  // instead of chipText
) { ... }

您可以在對應檔案中新增 fieldMappings 區塊，影響參數的對應方式。在本例中，包含 Chip 中 chipText 參數與 MyChip 中 description 參數的對應關係。

{
    "target": "MyChip",
    "package": "com.example.myApp",
    "fieldMappings": [
        {
            "type": "parameter",
            "source": "chipText",
            "target": "description"
        }
    ]
}

fieldMappings 區塊的類型包括：

parameter：將 UI 套件欄位對應至程式碼參數。
- source：UI 套件中指定的參數名稱。
- target：在目標程式碼元件中指定的參數名稱。
lambda：將 UI 套件欄位對應至內容 lambda。
- source：UI 套件中指定的參數名稱。
- target：在目標程式碼元件中指定的參數名稱。
modifier：將 UI 套件欄位對應至修飾符方法。

注意： 這個對應類型正在逐漸完善，特別是處理接收器範圍。
- source：UI 套件中指定的參數名稱。
- method：對產生的程式碼應叫用的修飾符物件方法。
- parameter：在指定修飾符方法中的參數名稱。
- library：為存取修飾符方法而匯入的限定套件名稱。
- scope：表示修飾符範圍的兩個值中的其中一個：
- any：可在任何接收器範圍內使用修飾符。
- relay：修飾符必須用於 Relay 的 RelayContainer 物件的接收器範圍。