将组件映射到现有代码

开发者可以通过提供界面软件包与现有代码组件之间的映射（而非生成的代码），自定义代码生成过程。如果现有实现具有生成的代码无法实现的功能，例如动画或复杂行为（如下拉菜单），这种做法会非常有用。

开发者指定如何使用映射文件映射组件。映射文件至少会告知代码生成器如何访问所需的可组合函数，以便创建正确的客户端代码。

示例如下：

在 Figma 中，设计人员创建了一个 Card 组件，其中包含 Play Bar 组件的一个实例，并打包这两个组件发送给开发者。

开发者从 Figma 导入界面软件包时，系统会在 ui-packages 中创建两个目录：card 和 play_bar。在开发者构建项目时，系统会创建两个可组合函数：Card 和 PlayBar。通常，由于 Card 包含 Figma 中的 Play Bar 实例，因此在代码中，Card 可组合函数包含对 PlayBar 可组合项的调用。

不过，设计人员和开发者希望 Card 改用现有的可组合项 MyExistingPlaybar，其具有在 Figma 中难以说明的功能。因此，开发者添加了一个名为 play_bar.map 的映射文件，用于将 play_bar 界面软件包映射到 MyExistingPlaybar：

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

现在，当开发者构建项目时，Card 会调用 MyExistingPlaybar，而不是 PlayBar。请注意，MyExistingPlaybar 的参数必须与 PlayBar 相同（但可以有一些差异，如下面的其他指令中所述）。

映射文件

在 Android Studio 项目中，映射文件会添加到 ui-packages 文件夹旁边的 ui-package-resources/mappings 下。Relay 会在构建期间查找您的映射文件。

给定映射文件的名称必须与其所替换组件的界面软件包文件夹的名称一致。因此，play_bar.map 会将 ui-packages/play_bar 文件夹中的界面软件包映射到现有代码组件。

映射的变体

如果 Figma 组件有多个变体，生成的可组合项将具有可对变体进行编码的枚举参数（如处理设计变体教程中所述）。如果您要将包含变体的 Figma 组件映射到现有代码，需要将其映射到一个与生成的可组合项具有相同参数的可组合项，只是枚举参数被替换为名为 design 的字符串参数。例如，假设有一个名为 Chip 的 Figma 组件，其中包含的变体的属性为 ChipType。Chip 生成的可组合签名如下所示：

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

如果您想让 Chip Figma 组件映射到现有的 MyChip 可组合项，则必须按以下方式指定 MyChip 的签名（假设没有指定其他指令）：

@Composable
fun MyChip
    modifier: Modifier = Modifier,
    design: String = "ChipType=Red",  // See note below
    chipText: String
) { ... }

从概念上来说，这表明现有的代码组件能够具有与 Figma 组件相同的设计变体。

其他指令

假设我们要指定可组合函数作为以下签名：

@Composable
fun MyChip(
    modifier: Modifier = Modifier,
    design: String = "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 块的类型包括：

type: parameter 将界面软件包字段映射到代码参数。
- source：界面软件包中指定的参数名称。
- target：目标代码组件中指定的参数名称。
type: lambda 将界面软件包字段映射到内容 lambda。
- source：界面软件包中指定的参数名称。
- target：目标代码组件中指定的参数名称。
type: modifier 将界面软件包字段映射到修饰符方法。注意：此映射类型正在逐渐完善，尤其是对接收器范围的处理。
- source：界面软件包中指定的参数名称。
- method：应在生成的代码中调用的修饰符对象的方法。
- parameter：指定的修饰符方法中的参数名称。
- library：为访问修饰符方法而导入的限定软件包名称。
- scope：表示修饰符范围的两个值之一：
- any：该修饰符可以在任何接收器范围内使用。
- relay：该修饰符必须在 Relay 的 RelayContainer 对象的接收器范围内使用。

另请参阅

映射组件教程，以了解深入讨论和示例