> ## Documentation Index > Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt > Use this file to discover all available pages before exploring further. # 配置映射 > 如何在知行之桥中配置映射，包括带注释的界面元素、节点类型、Foreach 循环、AI 辅助映射和最佳实践。 export const companyName = "知行软件"; export const siteNameShort = "知行之桥"; 下图为已完成的 [XML Map](/26.2/self-hosted/zh/connectors/xml-map/xml-map) 映射页面，其中已对屏幕上的每个元素进行了注释（[EDI 文档映射](/26.2/self-hosted/zh/tpmc/edi-mapping) 类似）。每个数字对应下面的一个描述。 1. 文档或端口名称。 2. 端口类型。 3. 映射的测试状态。值为**测试成功**、**测试有错误**或**未测试**。 4. 切换 XML 流的开启或关闭（默认开启）。开启时，映射引擎会在完成循环后丢弃映射中最顶层 `Foreach` 当前迭代的文档对象模型 (DOM)。这可以显著提高大型 XML 文档的性能。当映射引擎无法解析映射时，它会自动关闭 XML 流。 5. 在映射的常规视图和紧凑视图之间切换（紧凑视图对于大型模板文件很有帮助）。 6. 切换是否显示或隐藏 XML 属性。 7. 刷新映射。 8. 启动 [AI 辅助映射](#ai-辅助映射)工具。 9. 打开**测试映射**页面。测试结果显示在 #3 中。（有关更多信息，请参阅[测试映射](#测试映射)。） 10. 保存映射。 11. 选定的源模板文件。 12. 映射的方向。 13. 选定的目标模板文件。 14. 源端和目标端的搜索栏。 15. 源 XML 的结构。 16. 父节点的名称。 17. 叶节点的名称。 18. 目标文档的结构。 19. 已完成的映射。 ## 了解源和目标 要定义映射，请点击左侧窗格中的节点并将其拖动到右侧窗格中其对应的对象上。选中某个节点后，其连接线为蓝色，其他所有线均为黑色。 在源树或目标树中拖放元素时，拖放节点上的一条或两条蓝线会变暗/处于活动状态，如下图所示。如果两条蓝线都处于活动状态，则被拖动的节点将创建为拖放节点的*兄弟*。如果只有右侧的蓝线处于活动状态，则被拖动的节点将创建为拖放节点的*子级*。在下图中，N103 节点从 N104 下方移至 N102 节点的直接兄弟，因此两条蓝线均突出显示。 要移除映射，请将鼠标悬停在映射的一端，然后点击**移除映射**。完成映射定义后，点击**保存**。 ## 映射节点 父节点和叶节点定义 XML 数据的层次结构，其中父节点将相关元素分组，叶节点表示要映射的实际数据值。 * **父节点**：XML 映射树中包含叶元素但没有值的节点。父节点类似于 [TPMC](/26.2/self-hosted/zh/tpmc/tpmc) 中的[表节点](/26.2/self-hosted/zh/tpmc/edi-mapping#table-nodes)。 * **叶节点**：包含值但没有子元素的节点。叶节点类似于 TPMC 中的[列节点](/26.2/self-hosted/zh/tpmc/edi-mapping#column-nodes)。 以下部分详细介绍了父节点和叶节点选项。 ### 父节点 #### XML 父元素 如前所述，映射编辑器中的树有两种类型的节点： * *父节点* 有子节点但没有值。 * *叶节点* 有值但没有子节点。 源中的父节点只能拖动到目标中的父节点上。 将源父节点拖动到目标父节点上会在源节点和目标节点之间建立 `Foreach` 关系。这意味着源元素的每次出现都会生成一个对应的目标元素，包括目标元素的所有子元素。 一旦建立了 Foreach 关系，目标中就会出现一个 xpath，如下图所示。输入 XML 中此路径上的元素会生成输出节点及其子节点的新实例。换句话说，Foreach 关系指示映射引擎循环遍历源中的给定 xpath，并为找到的每个元素生成映射的目标结构。目标树视图中的 xpath 就是映射引擎循环遍历的 xpath。 #### 虚拟循环 虚拟循环是一种特殊节点，可以将其添加到目标结构中，但该节点不会直接出现在输出 XML 中。它提供了一个机会，可以实现影响输出中其他（非虚拟）节点的外观和/或值的逻辑。 它的功能与父节点之间的 Foreach 映射相同，只是父节点不会出现在输出 XML 中。这允许您将源中的重复元素展平为目标中的非层次结构。通过示例更容易理解这一点。 以以下输入 XML 为例： ```xml theme={null} 212.5 9.2 5.1 ``` 这需要映射到包含所有 *DataReading* 数据的平面结构： ```xml theme={null} 212.5 9.2 5.1 ``` 可以通过与目标中与源中每个 *DataReading* 元素对应的循环节点建立 Foreach 关系来实现此目的： 如果在 *DataReading* 和 *OutputData* 之间建立 Foreach 关系，则结果中会重复 *OutputData* 元素。循环节点可以避免这种层级重复，并将值展平到单个 *OutputData* 元素中。 要添加上例中所示的循环节点，请按以下步骤操作： 1. 右键单击 *TemperatureReading* 节点，或单击省略号，然后选择**添加节点 > 添加循环**。为循环指定一个有意义的名称，然后点击复选标记进行保存。 2. 将源 *DataReading* 节点拖到循环上以创建 Foreach 关系。 3. 将源 *Temperature* 节点映射到目标 *TemperatureReading* 节点。 #### 虚拟条件 虚拟条件基于共享条件将输出元素组合在一起。如果条件为真，则条件节点的所有子节点都会出现在输出中；如果条件为假，则不会出现。 这在功能上相当于将相同的条件分别添加到每个单独的节点。对于影响多个不同节点的条件，通常更方便的做法是创建一个条件节点，然后将所有相关的输出节点设为该条件节点的子节点。 要创建条件虚拟节点，请按以下步骤操作： 1. 右键单击目标节点或单击省略号，然后选择**添加节点 > 添加条件**。 2. 单击新条件旁边的漏斗图标以创建条件规则。有关详细信息，请参阅[使用条件编辑器](./mapping-condition-editor)。 ### 叶节点 #### XML 叶元素 将源叶节点拖放到目标叶节点上，会指示映射引擎使用源元素的值填充目标元素。拖放到目标节点后，目标树视图中将显示读取值的 xpath，如下图所示。 目标树视图中显示的 xpath 是*绝对*或*相对*的。绝对 xpath 以斜杠 (/) 开头，描述源中的完整 xpath，从文档的根开始。相对 xpath 不以斜杠开头，它们相对于父节点中设置的 Foreach 循环。 相对 xpath 可以相对于多个 Foreach 循环（只要元素有多个父元素，并且每个父元素都映射了 Foreach 关系）。要找到任何给定相对 xpath 的绝对 xpath，只需连接每个父级的 Foreach xpath，从文档顶部开始，直到到达当前节点。 #### XML 属性 除了元素值之外，要使用 XML 属性，请确保已启用映射页面顶部的**显示属性**设置（attributes）。启用后，编辑器将显示检测到的作为其所属元素子元素的所有属性。 所有 XML 属性名称都以 `@` 为前缀（`@` 符号在 XML 元素名称中无效）。此字符仅用于显示，在读取或写入属性时会被删除。 ##### 从源读取 XML 属性 启用**显示属性**开关后，XML 源中的任何属性都会在映射编辑器中显示为节点。您可以像其他节点一样将这些值拖放到目标节点上。节点显示 `@` 前缀，表示它们是 XML 属性，而不是 XML 元素，如下图所示。 ##### 在目标中写入 XML 属性 包含 XML 属性的目标模板会将属性节点显示为其所属元素的子节点，并且这些节点可以像任何其他值一样进行映射。 要向目标节点添加新属性，请右键单击或点击节点上的省略号，然后选择**添加节点 > 添加属性**。 属性名称始终以 `@` 前缀开头（此字符不包含在输出 XML 中）。 #### 标头 标头节点允许您将值映射为映射输出消息的标头。这些标头节点不包含在输出 XML 中，但会作为元数据消息标头添加到输出消息中。这些标头在整个流程中与消息保持一致，并且任何下游端口都可以根据需要引用它们的值，从而可以轻松跟踪数据在应用程序中的进度。标头节点会自动添加到节点值编辑器中的**消息头**选项卡中。要添加标头节点，请右键单击或点击现有节点上的省略号，然后选择**添加 > 添加标头**。 标头节点不会添加到[跟踪头](/26.2/self-hosted/zh/getting-started/administration/activity#tracked-headers)。您可以通过点击节点上的省略号并选择**添加跟踪**将非标头目标节点添加到跟踪头。有关更多信息，请参阅[消息头](./mapping-node-value-editor#message-headers)。 #### 代码脚本 代码脚本虚拟节点提供了编写自定义 {siteNameShort}Script 的机会，这些脚本无需返回输出值。通常，这些节点使用[变量](./mapping-node-value-editor#variables)或特殊的 `_map` 项来存储稍后需要在映射中引用但不需要在当前上下文中输出的值。 例如，[映射项](/26.2/self-hosted/zh/connectors/xml-map/xml-map-advanced#map-item)部分中描述的场景就非常适合使用虚拟代码脚本节点。订单项成本总和需要在计算该值的 `Foreach` 循环之外作为输出返回。因此，Foreach 循环中的虚拟代码脚本节点可以计算该值但不输出。然后，该值可以在循环之外的非虚拟节点中作为输出引用。 要创建代码脚本虚拟节点，请按以下步骤操作： 1. 右键单击目标节点或点击省略号，然后选择**添加节点 > 添加代码脚本**。 2. 输入**脚本名称**。 3. 提供脚本。编辑器会在您输入时验证表达式，因此如果您看到**无效脚本**消息，则表示存在语法问题。完成后，点击**添加脚本**。 #### 变量节点 在映射中的某个位置设置变量，并在之后的映射中再次引用这些变量会很有用。有关详细信息和示例，请参阅[变量](./mapping-node-value-editor#variables)。 ### 节点选项 要处理单个节点，请将鼠标悬停在节点上，然后右键单击或单击省略号以从一组附加选项中进行选择。选项会根据正在处理的节点类型而有所不同。本节介绍处理父节点、叶节点或文档节点时可用的选项。有关这些节点类型的详细信息，请参阅[表节点](/26.2/self-hosted/zh/tpmc/edi-mapping#table-nodes)和[列节点](/26.2/self-hosted/zh/tpmc/edi-mapping#column-nodes)。 * **重命名节点** 允许更改节点的名称。 * **编辑 XPath** 允许编辑节点 XPath（仅限已映射为 `Foreach` 的元素）。 * **删除节点** 允许您从文档中删除节点。 * **添加节点** * **添加兄弟节点** 可在所选节点的同一级别添加一个节点。 * **添加属性** 可为所选节点添加属性。 * **添加子节点** 会将一个节点添加为所选节点的子节点。 * **添加标头** 会创建一个标头节点，您可以将值映射到该标头节点。映射的值不会包含在输出文件中，但会作为标头添加到映射输出消息中。 * **添加循环** 会在所选节点上方创建一个循环节点，该节点将嵌套在循环节点中。有关更多信息，请参阅[映射循环](#映射循环)。 * **添加条件** 会打开[条件编辑器](./mapping-condition-editor)，您可以在其中添加条件，以便只有当条件为真时，数据才会更新插入到目标。 * **添加代码脚本** 会创建一个新的脚本节点作为目标元素的同级节点。使用**添加脚本**窗口命名脚本并提供自定义 {siteNameShort}Script。 * **添加变量** 会在所选节点下方创建一个变量节点。有关更多信息，请参阅[变量](./mapping-node-value-editor#variables)。 * **剪切节点** 将从当前位置剪切所选节点。 * **复制节点** 复制所选节点。 * **粘贴为子节点** 将剪切或复制的节点粘贴为所选节点的子节点。 * **添加跟踪** 将[跟踪头](/26.2/self-hosted/zh/getting-started/administration/activity#tracked-headers)添加到映射中。启用跟踪的节点会显示指南针图标。 还可以使用**编辑节点**打开**编辑节点值**页面。请参阅[使用节点值编辑器](./mapping-node-value-editor)。 ## AI 辅助映射 在实例上设置 [AI 设置](/26.2/self-hosted/zh/getting-started/administration/settings/ai-settings)并上传或设置源和目标模板文件后，可以使用任何受支持的大语言模型 (LLM) 来协助构建映射。此功能通过提供智能映射建议解决了映射配置难题，从而显著简化了创建精确数据转换的过程。 使用的 LLM 必须支持结构化输出。{companyName} 已确认以下模型提供可靠的结构化输出： * Claude: Opus 4.6 * Gemini: gemini-3-pro * Grok: grok-4-fast-non-reasoning * Ollama Cloud: glm-4.6 * OpenAI: gpt-5.4 要让 AI 生成整个映射，请点击页面顶部的 AI Assisted Mapping 图标。如果尝试使用不支持结构化输出的模型，该图标将被禁用。 或者，可以让 AI 在节点级别生成映射。右键单击源或目标端的父节点或使用省略号，选择 **AI 辅助映射**，然后选择以下选项之一： * 映射节点 * 映射子节点 * 节点和子节点 AI 生成映射后，可以根据需要进行调整。 如果在 [XML Map](/26.2/self-hosted/zh/connectors/xml-map/xml-map) 端口上使用此功能，可以自定义应用程序用于创建映射的用户提示和系统提示。有关详细信息，请参阅 [XML Map 高级设置](/26.2/self-hosted/zh/connectors/xml-map/xml-map-configuration#advanced-settings)。 ## 映射循环 创建父节点映射会在源节点和目标节点之间建立 `Foreach` 关系。这意味着源元素的每次出现都会生成一个对应的目标元素，包括目标元素的所有叶节点。创建叶节点映射会指示映射引擎使用源元素的值填充目标元素。 先映射父节点（Foreach 循环），然后再映射叶节点。建立循环关系需要了解源和目标 XML 结构：每当源中的重复元素应导致目标中的重复元素时，这些元素都应在 Foreach 关系中一起映射。 在 Foreach 循环中，叶元素 xpath 是相对于映射的 Foreach xpath 的。 作为一个非常简单的示例，请考虑以下源和目标 XML，其中嵌套 XML 结构应转换为扁平 XML 结构： ```xml theme={null}
``` ```xml theme={null} ``` 源中每次重复 *customer* 元素，目标中都会生成一个 *customerInfo* 元素，因此这些父元素应该映射在一起，形成 Foreach 关系。这样，每个叶元素的映射就很简单了： 请注意，叶元素的 xpath 是相对于父元素中的 xpath（定义 Foreach 关系的 xpath）。 ### 映射多个循环 映射通常需要在同一文档中建立多个 Foreach 循环关系。映射循环的原则保持不变：源文档中任何重复的父元素，如果在目标文档中应该生成重复的元素，都应该映射为循环。先映射外层循环，再映射内层循环（换句话说，从结构的顶部开始向下映射）。所有循环关系都应在映射任何叶元素之前进行映射。 举一个常见的例子，考虑将传入的采购订单报告映射到目标数据库。此类映射包含两个可能重复的不同元素结构，因此每个结构都需要一个 Foreach 关系：(1) 单个报告可能包含多个单独的订单，以及 (2) 单个订单可能包含多个行项目。 ### 示例输入 源模板结构可能如下所示： ```xml theme={null} John Doe 12/21/22 Hammer 1500 1 Standard claw hammer Nail 10 20 Ten penny nails 1700 4 ``` 为简洁起见，此示例仅包含一个 *WebOrder* 元素，但映射应该处理同一个 *OrderReport* 中包含多个 *WebOrder* 部分的情况。 ### 示例输出 此映射的输出应与数据库插入的 XML 模型匹配。数据库插入的 XML 模型由数据库端口（例如 MySQL、SQLite 和 CData 端口）自动创建，[数据库端口中的模板文件](/26.2/self-hosted/zh/connectors/xml-map/xml-map-template-files#template-files-from-database-connectors)部分介绍了如何在 XML Map 端口中将这些 XML 模型用作模板文件。 正确的数据库设计建议将数据插入两个单独的表中，一个用于 Orders，一个用于 Line Items。为此方法生成合适的输入映射可以生成如下模板结构： ```xml theme={null} ``` 在此示例中，*Order* 元素表示向 Orders 表中插入数据，而 *OrderLine* 元素表示向 Line Items 表中插入数据。生成的模板仅包含一个代表每个表的元素，但映射期间建立的 Foreach 关系可确保创建适当数量的插入数据。 *Order* 的其他子元素（*FirstName*、*LastName*、*Date*）表示 Orders 表中的列，而 *OrderLine* 的子元素（*SKU*、*Price* 等）表示 Line Items 表中的列。 ### 建立循环关系 源中的 *WebOrder* 元素应该会在 Orders 表中插入一条新数据，因此应将其拖放到目标中的 *Order* 元素上。同样，源中的 *Line* 元素应该会在 Line Items 表中插入一条新数据，因此应将其拖放到目标中的 *OrderLine* 元素上。 建立这两个 Foreach 关系后，映射编辑器应如下所示： 建立循环关系并删除所有不必要的目标元素后，可以映射叶元素以填充目标值： ## 不必要的父节点 建立 Foreach 关系时，源文件和目标文件中只需存在一个映射元素实例。换句话说，Foreach 关系负责确保输出元素的数量与相应输入元素的数量匹配。 为了更清楚地说明这一点，假设在[映射循环](#映射循环)示例中，源文件（输入 XML 的模板）包含多组 *customer* 元素组。在 *customer*（源）和 *customerInfo*（目标）之间建立单个 Foreach 关系，可确保 *customerInfo* 元素组的数量与任何输入文件中的 *customer* 元素组数量匹配。由于只需一个 *customer* 元素即可建立此 Foreach 关系，因此所有其他 *customer* 元素与映射无关，可以忽略或删除。 同样，如果上例中的目标文件包含多个 *customerInfo* 元素，则应删除除一个之外的所有元素。*customer* 和 *customerInfo* 之间的 Foreach 关系确保在 XML 输出中出现适当数量的 *customerInfo* 元素组。 ## 测试映射 使用**测试映射**按钮检查映射是否按预期工作。测试会使用源文件中的值填充目标元素，如下所示： 如果测试失败，**目标**窗格将提供失败的解释。 ## 映射最佳实践 Foreach 循环是映射目标文件中重复元素的强大工具。但是，遵循以下最佳实践至关重要，以确保功能正常并避免性能问题： * 使用大型 XML 文件时，避免将整个文件映射为 Foreach 循环。这种映射方式会指示映射引擎将整个文件加载到内存中，这可能会导致较长的处理时间。 * 相反，最佳做法是牢记完整的源文档结构，并且只为已知重复的元素创建 Foreach 关系（如上文[建立循环关系](#建立循环关系)中所述）。这种做法可以最大限度地减少与 Foreach 关系相关的性能影响。