Excel 端口 - 知行之桥文档

Excel 端口使用脚本模板在 Excel 工作表（.xlsx）和 XML 文件之间转换数据。

核心功能

在表格（Table）和模板（Template）模式下提供 Excel/XML 的双向转换
使用 Script 实现动态数据填充的高级模板系统
支持多个工作表，并可配置行/列范围

概览

Excel 端口可以配置为两种模式：表模式和模板模式。这些模式如下所述。

表模式

Excel 端口的默认模式是 Table。此模式仅支持将文件从 XLSX 转换为 XML。若要从 XML 转换为 XLSX，请使用 Template 模式。在表模式中，端口会像处理 CSV 文件一样处理输入 XLSX 文件。生成的输出 XML 文件具有以下结构，原始文件中的每一行（记录）都会成为根元素 Items 的子元素：

<Items>
 <Record>
  <field_0></field_0>
  <field_1></field_1>
  <field_2></field_2>
 </Record>
</Items>

模板模式

在 Template 模式中，端口使用模板文件执行转换。此模板文件与输出文件格式相匹配：

从 XML 转换为 Excel 时，模板文件是 Excel 文件。
从 Excel 转换为 XML 时，模板文件是 XML 文件。

这些模板文件使用 Script，将输入文件中的数据动态填充到输出文件中。有关更多信息，请参阅模板部分。

端口配置

本节包含所有可配置的端口属性。

设置

配置

与端口核心配置相关的设置。

设置	描述
端口 Id	端口的静态、唯一标识符。
端口类型	显示端口名称及其用途描述。
端口描述	一个可选字段，用于提供端口及其在流程中角色的自由格式描述。
Translation Mode	指定使用哪种方法（Table 或 Template）将输入文件转换为输出格式。有关更多信息，请参阅概览。
Column headers	（Table 模式）勾选此项后，转换会使用 XLSX 文件第一行中的值作为子元素的元素名称。如果未勾选，值元素会被赋予 field_0、field_1 等通用名称。
Template File	（Template 模式）作为输出模板的文件。数据会根据模板中的脚本动态添加到文件中。有关详细信息，请参阅模板部分。

高级设置

前面类别中未包含的设置。

设置	描述
Start Row	（Table 模式）工作表中用于输出表的第一行。
Start Column	（Table 模式）工作表中用于输出表的第一列。
End Column	（Table 模式）工作表中用于输出表的最后一列。如果未设置，则将第一行中第一个空单元格前面的列检测为工作表的结尾。
DateTime Format	（Table 模式）Excel 文档中 DateTime 值使用的格式。
Number Format	（Table 模式）Excel 文档中数字使用的格式。如果希望以相同方式处理文档中的所有数字，请设置此项。
Propagate Merged Cell Values	（Table 模式）在表模式下读取 Excel 时，勾选此项可将每个合并单元格的值传播到合并区域中的所有行。此选项可提供更完整的数据，但需要额外读取 Excel 文件，这可能会影响大型工作簿的性能。
本地文件方案	用于为端口输出的消息分配文件名的方案。可以在文件名中动态使用宏，以包含标识符和时间戳等信息。有关更多信息，请参阅宏。

高级页面

消息

日志

其他设置

设置	描述
处理延迟	放置在交易选项卡中的文件在处理前延迟的时间（以秒为单位）。这是旧版设置。最佳做法是使用 File 端口来管理本地文件系统，而不是使用此设置。

其他设置

自动化

与端口自动处理文件相关的设置。

自动化设置

设置	描述
发送	到达端口的消息是否自动进行处理。

性能

警报

SLA

模板

XML 到 Excel

下面的 XML 文件片段在 /Items/Orders 路径下包含一组元素。

<Items>
    <Orders>
        <OrderNo>PO0012345</OrderNo>
        <Customer>Teddy</Customer>
        <Date>04/19/2023</Date>
        <SubTotal>23.98</SubTotal>
        <Items>
            <Name>Teddy Bear</Name>
            <Cost>14.99</Cost>
            <Desc>Brown</Desc>
        </Items>
        <Items>
            <Name>Truck</Name>
            <Cost>8.99</Cost>
            <Desc>Red</Desc>
        </Items>
    </Orders>
</Items>

要将此 XML 文件转换为 XLSX，必须创建一个 Excel 模板。下图显示了一个使用 xmlDOMSearch 和 xpath 循环遍历 XML 文件元素的 Excel 模板示例：

每个 Excel 模板都必须包含以下元素，如上例所示：

静态列标题。在上例中为 Order Detail。
Excel 批注中的脚本。此脚本应使用 xmlDOMSearch 操作，在指定 XPath 处循环遍历输入 XML。在上例中，它包含在 arc:call 操作中。
Excel 单元格中的脚本。此脚本应使用 xpath 格式化器从给定 xpath 读取 XML 中的值。此 xpath 相对于 xmlDOMSearch 操作中指定的 xpath。

下面描述此示例中 xmlDOMSearch 操作和 xpath 格式化器的详细信息。

xmlDOMSearch

xmlDOMSearch 需要两个参数：

参数	描述
URI	要解析的 XML 文件的资源路径。`[filepath]` 属性会解析为端口的输入 XML 文件，URI 几乎总是应设置为此值。在上例中，文件路径使用 urlencode 格式化器进行 URL 编码，以确保文件路径中的特殊字符不会阻止端口读取文件：`[filepath \| urlencode]`
xpath	文档中要循环遍历的 XML 路径。该操作会针对指定 xpath 的每次出现进行循环。例如，使用 xpath `/Items/Orders` 时，根 Items 元素的每个子 Orders 元素都会在生成的 Excel 文件中产生一组新的输出。

xpath 格式化器

带有 xmlDOMSearch 操作的 Excel 批注围绕一块单元格，这些单元格通过 xpath 格式化器引用输入 XML。xpath 格式化器从输入 XML 中指定的 xpath 读取值。

此 xpath 相对于作为参数提供给 xmlDOMSearch 操作的路径。

在上例中，第一个单元格使用 [xpath("OrderNo")] 填充。由于此 xpath 是相对路径，因此该单元格会填充输入 XML 中以下路径的值：/Items/Orders/OrderNo。如果 xmlDOMSearch 操作循环多次（即找到该操作 xpath 参数的多个实例），则 Excel 批注之间的单元格块会重复。新单元格会垂直添加，因此在上例中，第二个 OrderNo 单元格会直接位于第一个 Notes 单元格下方。

Excel 到 XML

要从 XLSX 转换为 XML 文件，必须使用 Script 命令创建自定义 XML 模板。由于 XML 不支持与 Excel 文件相同的脚本功能，因此从 XLSX 转换为 XML 的结构和格式与从 XML 转换为 Excel 不同。

由于潜在的输入和输出结构范围很广，因此没有适用于所有转换需求的通用解决方案。下面显示的示例模板只是众多可能方案之一。你需要根据自己的需求创建模板。

此示例模板结合使用标准 XML 语法和 Script，从输入 Excel 文件读取、处理并转换数据。下面的 arc:set 行指定文件位置以及用于创建该文件的 Excel 版本。

<!-- Read Excel -->
<arc:set attr="xml.file" value="[FilePath]" />
<arc:set attr="xml.version" value="2007" />

下面的部分指定转换参数，并将标题映射为标准 XML 格式。参数 [_value | toalphanum | replace(' ','')] 表示 arc:set 命令应从 Excel 文件解析标题名称，将其转换为字母数字格式，删除空格，并将其指定为 XML 文件中的标题。

<!-- Always use first sheet-->
<arc:call op="excelListSheets" in ="xml" out="sheet">
  <arc:set attr="xml.sheet" value="[sheet.sheet]" />
  <arc:break />
</arc:call>

<!-- read the headers into an array-->
<arc:set attr="xml.map:headers" value="A1:*1" />
<arc:call op="excelGet" in="xml" out="header">
  <arc:enum attr="header.headers#">
    <arc:set attr="data.headernames#" value="[_value | toalphanum | replace(' ','')]" />
  </arc:enum>
</arc:call>

<arc:set attr="_log.info" value="[data.headernames#1]" />

<arc:enum range="A..Z">
  <arc:set attr="tmp.cells#" value="[_value]" />
</arc:enum>

下面的部分处理剩余数据，并根据指定结构构建数据列。

<!-- read the remaining cells -->
<arc:enum attr="data.headernames#">
  <arc:set attr="xml.map:[_value]" value="[tmp.cells#[_index]]2:[tmp.cells#[_index]]*" />
</arc:enum>

<!-- build the columns -->
<arc:call op="excelGet" in="xml" out="cols">
  <arc:map from="cols" to="data" map="*=*" />
</arc:call>

<Items>
  <arc:enum attr="data.[data.headernames#1]#"><arc:set attr="tmp.colIndex" value="[_index]" />
    <Record>
      <arc:enum attr="data.headernames#">
        <[_value]>[data.[_value]#[tmp.colIndex] | def]</[_value]>
      </arc:enum>
    </Record>
  </arc:enum>
</Items>

宏

示例

Excel 运算器

除了提供的操作之外，端口还可以提供将功能扩展到 Script 的操作。这些端口操作可以像任何其他 Script 操作一样调用，但有两个细节例外：

它们必须通过 connector.rsc 端点调用。
它们必须包含身份验证令牌。

例如，使用这两条规则调用端口操作可能如下所示：

<arc:set attr="in.myInput" value="myvalue" />
<arc:call op="connector.rsc/opName" authtoken="admin:1j9P8v8b9K0x6g5R5t7k" in="in" out="out">
  <!-- handle output from the op here -->
</arc:call>

下面列出了 Excel 端口功能特定的操作。

excelClose

关闭 Excel 连接。

可选参数

handle：Excel 文件的句柄。

输出属性

success：如果连接成功关闭，则为 True。

excelGet

查询指定的 Excel 工作表。

必需参数

sheet：Excel 工作表的名称。

可选参数

version：正在使用的 Excel 版本。默认值为 AUTO。仅当使用旧版 Excel 时才需要选择其他版本。
file：Excel 工作簿的路径。
handle：Excel 文件的句柄。
map:*：这组输入包含属性名称与要从电子表格中检索其值的单元格名称之间的映射。例如，属性名称 map:MyValue 的值为 C1 时，会推送一个名为 MyValue 的属性，其值为工作表中 C1 单元格中的值。可以指定单元格名称范围以检索一系列单元格值。

输出属性

*：取决于工作表内容和指定的查询。如果存在列标题，则会用于命名输出属性。

excelListSheets

列出指定 Excel 工作簿中的工作表。

可选参数

version：正在使用的 Excel 版本。默认值为 AUTO。仅当使用旧版 Excel 时才需要选择其他版本。
file：Excel 工作簿的路径。
handle：Excel 文件的句柄。

输出属性

isHidden：如果工作表在 Excel 中隐藏，则返回 true。
sheet：Excel 工作表的名称。 Note that the name ends with $. This is not required when specifying worksheet names to other operations.

excelOpen

打开现有 Excel 工作簿。

必需参数

file：Excel 工作簿的路径。

可选参数

version：正在使用的 Excel 版本。默认值为 AUTO。仅当使用旧版 Excel 时才需要选择其他版本。

输出属性

handle：用于执行其他操作的句柄。

​核心功能

​概览

​表模式

​模板模式

​端口配置

​设置

​配置

​高级设置

​高级页面

​消息

​日志

​其他设置

​其他设置

​自动化

​自动化设置

​性能

​警报

​SLA

​模板

​XML 到 Excel

​xmlDOMSearch

​xpath 格式化器

​Excel 到 XML

​宏

​示例

​Excel 运算器

​excelClose

​可选参数

​输出属性

​excelGet

​必需参数

​可选参数

​输出属性

​excelListSheets

​可选参数

​输出属性

​excelOpen

​必需参数

​可选参数

​输出属性

核心功能

概览

表模式

模板模式

端口配置

设置

配置

高级设置

高级页面

消息

日志

其他设置

其他设置

自动化

自动化设置

性能

警报

SLA

模板

XML 到 Excel

xmlDOMSearch

xpath 格式化器

Excel 到 XML

宏

示例

Excel 运算器

excelClose

可选参数

输出属性

excelGet

必需参数

可选参数

输出属性

excelListSheets

可选参数

输出属性

excelOpen

必需参数

可选参数

输出属性