将组件映射到现有代码

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

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

示例如下：

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

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

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

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

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

映射文件

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

生成映射文件

Relay 可以为任何导入的界面软件包生成映射文件。关注这些活动 步骤：

1. 右键点击软件包文件夹或目标 ui-package 内的任何文件 文件夹中。选择 Generate mapping file。

   

2. 在对话框中配置以下选项：

   

   • File location：设置生成的映射文件的位置。

   • 目标可组合项：设置改用的自定义可组合项 来代替生成的可组合项您可以选择使用 现有的可组合项，或从对话框中创建新的可组合项。创建新的 可组合函数会创建一个可组合函数，其参数与 界面软件包。

   。
   注意： 目标可组合项应以大写字母开头。
   • 生成的文件：设置 generateImplementation 和 generatePreview 选项。请参阅映射文件内容。 以了解详情。

3. 点击 Generate mapping file（生成映射文件）。系统会在 包含指定配置的 ui-package-resources/mapping 文件夹。

您也可以从 Relay 中打开 Generate mapping file 对话框 使用以下步骤打包模块界面：

1. 点击目标 ui-package 内界面软件包的任意文件 文件夹中。

2. 如果 Relay 工具窗口未自动打开，请点击 Relay 图标 打开窗口。

3. 点击 Package Options 下的 Generate mapping file按钮。

   

   注意 ：如果所选界面软件包存在映射文件，则系统会显示用于打开的链接 将改为显示文件。

映射文件名

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

映射文件内容

映射文件包含以下属性：

• target：（必需）自定义可组合函数的名称。修改者 默认情况下，这是由生成的代码创建的函数的名称。

  "target" : "CustomComposableName"
  

• package：（必需）自定义可组合项所在的软件包的名称 位置默认情况下，这是由系统生成的函数 代码。

  "package" : "com.example.podcastapp.ui.components"
  

• generateImplementation：（可选）true 或 false。如果值为 true，则 系统仍在生成的代码中创建此界面软件包的实现 文件。如果为 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 代码块，该代码块会影响 参数进行映射。在本例中，它包含来自 chipText 的映射。 将 Chip 中的形参设置为 MyChip 中的 description 形参。

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

fieldMappings 块的类型包括：

• parameter：将界面软件包字段映射到代码参数。
  • source：界面软件包中指定的参数名称。
  • target：目标代码组件中指定的参数名称。
• lambda：将界面软件包字段映射到内容 lambda。
  • source：界面软件包中指定的参数名称。
  • target：目标代码组件中指定的参数名称。

• modifier：将界面软件包字段映射到修饰符方法。

  注意 ：这种映射类型正在逐步完善中，尤其是对 接收器范围。
  • source：界面软件包中指定的参数名称。
  • method：针对应在以下参数中调用的修饰符对象的方法 生成的代码
  • parameter：指定的修饰符方法中的参数名称。
  • library：为访问修饰符方法而导入的限定软件包名称。
  • scope：表示修饰符范围的两个值之一：
  • any：该修饰符可以在任何接收器范围内使用。
  • relay：该修饰符必须在 Relay 的 RelayContainer 对象。