本地 Excel 文件

本地 Excel 文件 是一个办公协同插件，以插件能力的形式出现在指令树「扩展能力」中。安装或内置加载后，可把插件里的节点拖到工作流画布使用。

插件标识：rpa-plugin-excel
插件分类：办公协同插件
节点数量：36 个

先选使用方式

方式	怎么用	适合人群
可视化编排（推荐）	在「扩展能力」中找到本地 Excel 文件，拖入需要的节点并填写参数	大多数用户，适合按表单配置插件能力
代码编排（执行指令 XML）	通过「执行指令（XML）」调用节点的 `type` 与参数	需要动态拼装、循环调用或批量处理的用户

什么时候用？

本地 .xlsx / .xlsm 文件操作（基于 exceljs，跨平台 Mac/Win/Linux，无需安装 Microsoft Excel）。覆盖工作簿管理（含新建空白工作簿 / 复制·重命名 Sheet）/ 单元格读写 / 查找定位 / 公式 / 格式 / 筛选 / 行列（含追加行）/ 数据清洗（去重·排序）/ 转换共 36 个原子节点。所有节点支持 handle 长链路 + filePath 单步两种模式，handle 模式下不会每次都重新 open/save，适合批量改写大文件。
需要在自动化流程中复用该插件提供的读取、写入、同步或处理能力。

使用前确认

该插件未声明独立连接，通常依赖当前浏览器登录态、本地文件或节点参数。
办公协同类能力需要确认文件、表格、空间或数据库的访问权限。
建议先运行连通性、查询或只读节点，确认权限和参数正确后再执行写入类节点。

节点总览

节点名称	节点标识	说明
新建工作簿（Excel）	`CreateWorkbook`	从零新建一个空白 .xlsx 工作簿并写入磁盘。默认 keepOpen=true 会返回 handle，可直接接 SetCell / AppendRow / SaveAs 继续写。目标已存在且 overwrite=false 时报 FILE_EXISTS。适合「采集结果落到一个新表」这类场景。
打开工作簿（Excel）	`OpenWorkbook`	打开本地 .xlsx / .xlsm 文件，返回 workbook handle 与 sheets 列表。长链路批量改写时强烈推荐先 Open 拿 handle，否则每次节点都会重新 open/save 文件。
关闭工作簿（Excel）	`CloseWorkbook`	释放 OpenWorkbook 拿到的 handle。可选 save=true 在释放前写回源路径，等价于 SaveAs+Close 两步合并。
保存工作簿（Excel）	`SaveAs`	把工作簿写到磁盘。savePath 为空则写回 handle/filePath 的源路径；savePath 不空则另存为新文件（父目录会自动创建）。
列出 Sheet 页（Excel）	`ListSheets`	列出当前工作簿内全部 sheet 页（name + index + rowCount + columnCount + state）。
新建 Sheet 页（Excel）	`AddSheet`	在当前工作簿末尾新建一个 worksheet。同名 sheet 已存在会报 SHEET_NAME_DUPLICATE。
重命名 Sheet 页（Excel）	`RenameSheet`	重命名一个 worksheet。新名称与其它 sheet 重名会报 SHEET_NAME_DUPLICATE。
复制 Sheet 页（Excel）	`CopySheet`	在同一工作簿内复制一个 worksheet（含值 / 样式 / 合并单元格 / 行高列宽）。newName 留空时自动取「<源名> (2)」。常用于多表汇总时先复制模板页。
读取单元格（Excel）	`GetCell`	读取单个 cell 的值，自动展开公式 cell（返回 result）/ 富文本 / 超链接。
写入单元格（Excel）	`SetCell`	向单格写入值。value 支持字面（数字 / 字符串 / 布尔）/ null / JSON 数组对象 / { formula:“SUM(A1:A10)” } / { hyperlink:“https://…”, text:”…” }。
读取区域（Excel）	`GetRange`	读取一个矩形 / 整行 / 整列区域，返回二维数组。
写入区域（Excel）	`SetRange`	把 JSON 二维数组写到以 startCell 为左上角的区域。每行可不等长（按最长补 null）。
读取已用区域信息（Excel）	`GetUsedRange`	返回 sheet 当前的已用边界：行数 / 列数 / 最后一行 / 最后一列 / 已用区域地址 / 下一空行号。常配合 AppendRow、SetRange 定位「数据写到哪」。
查找单元格（Excel）	`FindCell`	在区域 / 整个 sheet 内查找匹配 value 的单元格，返回命中位置（地址 / 行号 / 列号 / 值）。matchMode 支持 eq/contains/startsWith/endsWith/regex；findAll=true 返回全部命中。常用于「定位某订单号在第几行」。
清空单元格 / 区域（Excel）	`ClearCell`	把区域内的 cell 值与公式清空。可选 alsoStyle=true 同时清掉字体 / 填充等样式。
合并 / 拆分单元格（Excel）	`MergeCells`	对一个区域执行 merge 或 unmerge。range 必须跨多格。
写入公式（Excel）	`SetFormula`	在单元格写入公式。exceljs 不会主动计算公式 —— result 字段会保持 undefined，需要用 Excel/WPS 打开后或 EvaluateFormula 才能读到值。
公式向下填充（Excel）	`FillDownFormula`	把源 cell 的公式按相对引用平移后向下填充 N 行。$A1 / A$1 / $A$1 的绝对引用会被保留。
公式向右填充（Excel）	`FillRightFormula`	把源 cell 的公式按相对引用平移后向右填充 N 列。
读取公式结果（Excel）	`EvaluateFormula`	读取公式 cell 的「上次计算结果」。注意：exceljs 不会重新计算公式，只能读出文件里上次 Excel 保存时缓存的 result。如果刚 SetFormula 还没用 Excel 打开过，evaluated 会是 false。
文本转数字（Excel）	`TextToNumber`	把区域内「看起来像数字的字符串」转成真数值。支持 “1,234.56” 千位分隔，自动去掉 numFmt=”@“。
数字转文本（Excel）	`NumberToText`	把区域内的数字 / 日期转成字符串，同时把 numFmt 设为 ”@“。
设置日期格式（Excel）	`SetDateFormat`	给区域 cell 设置日期 numFmt（默认 yyyy-mm-dd）。不做「字符串 → Date 类型」转换，请先 SetCell value=new Date(…) 再用本任务。
设置单元格样式（Excel）	`SetCellFormat`	通用样式入口：numFmt + font(bold/italic/size/color/name) + alignment(horizontal/vertical/wrapText) + fill(color/pattern)。color 接受 “#FF0000” 或 ARGB 8 位。
设置筛选（Excel）	`SetFilter`	在数据区域上设置 autoFilter，并按 filters 条件（多条件 AND）隐藏不匹配的数据行（首行视为表头）。op 支持 eq/ne/gt/gte/lt/lte/contains/startsWith/endsWith/in/notIn/empty/notEmpty。
清除筛选（Excel）	`ClearFilter`	清掉 worksheet 的 autoFilter，并把所有 row.hidden 设回 false。
读取可见行（Excel）	`GetFilteredRows`	返回 sheet 中所有 hidden=false 的行数据（跳过隐藏行）。常和 SetFilter 配对使用。
追加行（Excel）	`AppendRow`	把一行 / 多行数据追加到 sheet 已用区域末尾，自动定位末尾行。values 支持一维数组（单行）、二维数组（多行）、对象（按表头映射列）、对象数组。对象模式下若表头行为空，默认用对象 key 自动写表头。最常用于「采集一条数据写到结果表」。
插入行（Excel）	`InsertRows`	在 beforeRow 之前插入 count 个空行。exceljs spliceRows 会自动 shift 后续行与公式。
删除行（Excel）	`DeleteRows`	从 startRow 起删 count 行。
插入列（Excel）	`InsertColumns`	在 beforeColumn 之前插入 count 个空列。
删除列（Excel）	`DeleteColumns`	从 startColumn 起删 count 列。
删除重复行（Excel）	`RemoveDuplicateRows`	删除重复行（保留首次出现），删除的是整行（含区域外的列一并上移）。hasHeader=true 时首行表头不参与判重且始终保留。columns 指定判重依据的列（绝对列，如 “A,C”），缺省按区域内所有列判重。
区域排序（Excel）	`SortRange`	对区域按一个或多个列排序（整行搬运）。hasHeader=true 时首行表头保持在顶部。sortBy 为 JSON 数组，column 为绝对列（字母或数字），order asc/desc，numeric=true 按数值比。空白单元格升降序都沉底。⚠️ range 必须覆盖数据的所有列，否则区域外的列不会跟着重排会导致行内错位；公式列排序后相对引用不会重新调整，排序键建议用静态值。不迁移逐行样式 / 行高。
xlsx 转 CSV（Excel）	`XlsxToCsv`	把工作簿的某个 sheet 导出为 CSV。支持 utf8 / utf8-bom 编码、自定义分隔符；visibleOnly=true 时跳过筛选隐藏行。
CSV 转 xlsx（Excel）	`CsvToXlsx`	把 CSV 文件转成 xlsx。内置 RFC 4180 解析器，支持引号转义。hasHeader=true 时把首行设为粗体。

节点参数与输出

新建工作簿（Excel）

节点标识： CreateWorkbook
节点说明： 从零新建一个空白 .xlsx 工作簿并写入磁盘。默认 keepOpen=true 会返回 handle，可直接接 SetCell / AppendRow / SaveAs 继续写。目标已存在且 overwrite=false 时报 FILE_EXISTS。适合「采集结果落到一个新表」这类场景。
XML 示例：

<CreateWorkbook filePath="" sheetName="Sheet1" overwrite="false" keepOpen="true" outKey="workbook" />

界面名称	代码属性名	类型	必填	默认值	说明
新文件路径	`filePath`	string	是	-	/Users/xxx/result.xlsx 或 C:\result.xlsx
首个 Sheet 名称	`sheetName`	string	否	`Sheet1`
已存在则覆盖	`overwrite`	boolean	否	-	false 时若目标文件已存在会报错，避免误覆盖
保持打开并返回 handle	`keepOpen`	boolean	否	`true`	true → 输出 data.handle，可继续用 handle 批量写后再 SaveAs/CloseWorkbook
输出变量名	`outKey`	output	否	`workbook`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`workbook`	object	{ ok:true, data:{ handle?, filePath, sheets:[{name,index,rowCount,columnCount}] }, … }

打开工作簿（Excel）

节点标识： OpenWorkbook
节点说明： 打开本地 .xlsx / .xlsm 文件，返回 workbook handle 与 sheets 列表。长链路批量改写时强烈推荐先 Open 拿 handle，否则每次节点都会重新 open/save 文件。
XML 示例：

<OpenWorkbook filePath="" outKey="workbook" />

界面名称	代码属性名	类型	必填	默认值	说明
Excel 文件路径	`filePath`	string	是	-	/Users/xxx/data.xlsx 或 C:\data.xlsx
输出变量名	`outKey`	output	否	`workbook`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`workbook`	object	{ ok:true, data:{ handle, filePath, sheets:[{name,index,rowCount,columnCount}] }, durationMs } 或 { ok:false, error, code, category, hint? }

关闭工作簿（Excel）

节点标识： CloseWorkbook
节点说明： 释放 OpenWorkbook 拿到的 handle。可选 save=true 在释放前写回源路径，等价于 SaveAs+Close 两步合并。
XML 示例：

<CloseWorkbook handle="" save="true" outKey="closed" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	是	-	OpenWorkbook 返回的 data.handle
释放前先保存	`save`	boolean	否	-
输出变量名	`outKey`	output	否	`closed`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`closed`	object	{ ok:true, data:{ handle, released, savedTo?, alreadyClosed? }, … }

保存工作簿（Excel）

节点标识： SaveAs
节点说明： 把工作簿写到磁盘。savePath 为空则写回 handle/filePath 的源路径；savePath 不空则另存为新文件（父目录会自动创建）。
XML 示例：

<SaveAs handle="" savePath="" outKey="savedWorkbook" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-	与 filePath 二选一；handle 模式不会重新打开文件
源 Excel 文件路径	`filePath`	string	否	-	无 handle 时使用；本任务会打开后立即保存
另存为目标路径	`savePath`	string	否	-	为空则覆盖源路径
输出变量名	`outKey`	output	否	`savedWorkbook`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`savedWorkbook`	object	{ ok:true, data:{ savedTo, sourcePath, handle? }, … }

列出 Sheet 页（Excel）

节点标识： ListSheets
节点说明： 列出当前工作簿内全部 sheet 页（name + index + rowCount + columnCount + state）。
XML 示例：

<ListSheets handle="" outKey="sheets" />

界面名称	代码属性名	类型	必填	默认值
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
输出变量名	`outKey`	output	否	`sheets`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`sheets`	object	{ ok:true, data:{ sheets:[{name,index,rowCount,columnCount,state?}] }, … }

新建 Sheet 页（Excel）

节点标识： AddSheet
节点说明： 在当前工作簿末尾新建一个 worksheet。同名 sheet 已存在会报 SHEET_NAME_DUPLICATE。
XML 示例：

<AddSheet handle="" sheetName="" activate="false" outKey="newSheet" />

界面名称	代码属性名	类型	必填	默认值
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
新 Sheet 名称	`sheetName`	string	是	-
设为活动 Sheet	`activate`	boolean	否	-
输出变量名	`outKey`	output	否	`newSheet`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`newSheet`	object	{ ok:true, data:{ name, index, handle? }, … }

重命名 Sheet 页（Excel）

节点标识： RenameSheet
节点说明： 重命名一个 worksheet。新名称与其它 sheet 重名会报 SHEET_NAME_DUPLICATE。
XML 示例：

<RenameSheet handle="" sheet="" newName="" outKey="renameSheetResult" />

界面名称	代码属性名	类型	必填	默认值
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
当前 Sheet（名称或 0-indexed）	`sheet`	string	是	-
新名称	`newName`	string	是	-
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`renameSheetResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`renameSheetResult`	object	{ ok:true, data:{ oldName, newName, index }, … }

复制 Sheet 页（Excel）

节点标识： CopySheet
节点说明： 在同一工作簿内复制一个 worksheet（含值 / 样式 / 合并单元格 / 行高列宽）。newName 留空时自动取「<源名> (2)」。常用于多表汇总时先复制模板页。
XML 示例：

<CopySheet handle="" sheet="" newName="" outKey="copySheetResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
源 Sheet（名称或 0-indexed）	`sheet`	string	是	-
目标 Sheet 名	`newName`	string	否	-	留空自动取唯一名「<源名> (2)」
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`copySheetResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`copySheetResult`	object	{ ok:true, data:{ sourceName, newName, index }, … }

读取单元格（Excel）

节点标识： GetCell
节点说明： 读取单个 cell 的值，自动展开公式 cell（返回 result）/ 富文本 / 超链接。
XML 示例：

<GetCell handle="" sheet="" cell="A1" outKey="cellValue" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet（名称或 0-indexed）	`sheet`	string	否	-	缺省取第 1 个
单元格	`cell`	string	是	-	A1
输出变量名	`outKey`	output	否	`cellValue`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`cellValue`	object	{ ok:true, data:{ value, address, numFmt?, formula?, hyperlink? }, … }

写入单元格（Excel）

节点标识： SetCell
节点说明： 向单格写入值。value 支持字面（数字 / 字符串 / 布尔）/ null / JSON 数组对象 / { formula:“SUM(A1:A10)” } / { hyperlink:“https://…”, text:”…” }。
XML 示例：

<SetCell handle="" sheet="" cell="A1" value="123" outKey="setCellResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
单元格	`cell`	string	是	-	A1
写入值	`value`	string	是	-	数字 / 字符串 / true\|false\|null / JSON 字面值
数字格式	`numFmt`	string	否	-	可选；如 “0.00” / “yyyy-mm-dd” / ”@“（强制文本）
transient 模式自动保存	`autoSave`	boolean	否	`true`	仅在不传 handle 时生效；handle 模式必须显式 SaveAs/CloseWorkbook
输出变量名	`outKey`	output	否	`setCellResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`setCellResult`	object	{ ok:true, data:{ sheet, address, value, savedTo?, handle? }, … }

读取区域（Excel）

节点标识： GetRange
节点说明： 读取一个矩形 / 整行 / 整列区域，返回二维数组。
XML 示例：

<GetRange handle="" sheet="" range="A1:C10" outKey="rangeValues" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
区域	`range`	string	是	-	A1:C10 / A1 / A:A / 3:5
包含 cell 元信息	`includeMeta`	boolean	否	-	true → values 每项是 {value, numFmt?, formula?, hyperlink?, address} 对象
按表头读成对象	`asObjects`	boolean	否	-	true → 区域首行视为表头，其余行读成 { 表头:值 } 对象数组，循环里用 row[“订单号”] 更直观；与 includeMeta 互斥，本项优先
输出变量名	`outKey`	output	否	`rangeValues`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`rangeValues`	object	asObjects=false：{ ok:true, data:{ sheet, range, rows, cols, values:二维数组 } }；asObjects=true：{ ok:true, data:{ sheet, range, rows, cols, headers:[…], values:[{表头:值},…] } }

写入区域（Excel）

节点标识： SetRange
节点说明： 把 JSON 二维数组写到以 startCell 为左上角的区域。每行可不等长（按最长补 null）。
XML 示例：

<SetRange handle="" sheet="" startCell="A1" values="[[1,2],[3,4]]" outKey="setRangeResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
起始单元格	`startCell`	string	是	-	A1
二维数据	`values`	json	是	-	[[“姓名”,“年龄”],[“张三”,18]]
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`setRangeResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`setRangeResult`	object	{ ok:true, data:{ sheet, range, rows, cols, savedTo?, handle? }, … }

读取已用区域信息（Excel）

节点标识： GetUsedRange
节点说明： 返回 sheet 当前的已用边界：行数 / 列数 / 最后一行 / 最后一列 / 已用区域地址 / 下一空行号。常配合 AppendRow、SetRange 定位「数据写到哪」。
XML 示例：

<GetUsedRange handle="" sheet="" outKey="usedRange" />

界面名称	代码属性名	类型	必填	默认值
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
输出变量名	`outKey`	output	否	`usedRange`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`usedRange`	object	{ ok:true, data:{ sheet, isEmpty, rowCount, columnCount, lastRow, lastColumn, lastColumnNumber, usedRange, nextRow }, … }

查找单元格（Excel）

节点标识： FindCell
节点说明： 在区域 / 整个 sheet 内查找匹配 value 的单元格，返回命中位置（地址 / 行号 / 列号 / 值）。matchMode 支持 eq/contains/startsWith/endsWith/regex；findAll=true 返回全部命中。常用于「定位某订单号在第几行」。
XML 示例：

<FindCell handle="" sheet="" value="" matchMode="eq" findAll="false" outKey="findResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
查找目标	`value`	string	是	-	支持 JSON 字面：123 / “待处理” / true
查找区域	`range`	string	否	-	缺省取整个已用区域
匹配方式	`matchMode`	select	否	`eq`
区分大小写	`matchCase`	boolean	否	-
返回全部命中	`findAll`	boolean	否	-	false 只返回第一个命中
输出变量名	`outKey`	output	否	`findResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`findResult`	object	{ ok:true, data:{ found, count, first?:{address,row,col,value}, matches:[{address,row,col,value}] }, … }

清空单元格 / 区域（Excel）

节点标识： ClearCell
节点说明： 把区域内的 cell 值与公式清空。可选 alsoStyle=true 同时清掉字体 / 填充等样式。
XML 示例：

<ClearCell handle="" sheet="" range="A1:C10" alsoStyle="false" outKey="clearResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
区域	`range`	string	是	-	A1:C10
同时清掉样式	`alsoStyle`	boolean	否	-
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`clearResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`clearResult`	object	{ ok:true, data:{ sheet, range, clearedCells, savedTo?, handle? }, … }

合并 / 拆分单元格（Excel）

节点标识： MergeCells
节点说明： 对一个区域执行 merge 或 unmerge。range 必须跨多格。
XML 示例：

<MergeCells handle="" sheet="" range="A1:C1" action="merge" outKey="mergeResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
区域	`range`	string	是	-	A1:C1
操作	`action`	select	否	`merge`
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`mergeResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`mergeResult`	object	{ ok:true, data:{ sheet, range, action }, … }

写入公式（Excel）

节点标识： SetFormula
节点说明： 在单元格写入公式。exceljs 不会主动计算公式 —— result 字段会保持 undefined，需要用 Excel/WPS 打开后或 EvaluateFormula 才能读到值。
XML 示例：

<SetFormula handle="" sheet="" cell="A1" formula="SUM(B1:B10)" outKey="setFormulaResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
单元格	`cell`	string	是	-	A1
公式	`formula`	string	是	-	可带 / 不带 leading ’=‘
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`setFormulaResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`setFormulaResult`	object	{ ok:true, data:{ sheet, address, formula }, … }

公式向下填充（Excel）

节点标识： FillDownFormula
节点说明： 把源 cell 的公式按相对引用平移后向下填充 N 行。$A1 / A$1 / $A$1 的绝对引用会被保留。
XML 示例：

<FillDownFormula handle="" sheet="" sourceCell="C2" targetRows="100" outKey="fillDownResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
源单元格	`sourceCell`	string	是	-	已经包含公式的格
向下填充行数	`targetRows`	number	是	`1`	10
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`fillDownResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`fillDownResult`	object	{ ok:true, data:{ sheet, sourceCell, formulaTemplate, filledCells:[“C3”,…] }, … }

公式向右填充（Excel）

节点标识： FillRightFormula
节点说明： 把源 cell 的公式按相对引用平移后向右填充 N 列。
XML 示例：

<FillRightFormula handle="" sheet="" sourceCell="B3" targetCols="10" outKey="fillRightResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
源单元格	`sourceCell`	string	是	-	B3
向右填充列数	`targetCols`	number	是	`1`
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`fillRightResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`fillRightResult`	object	{ ok:true, data:{ sheet, sourceCell, formulaTemplate, filledCells:[“C3”,“D3”,…] }, … }

读取公式结果（Excel）

节点标识： EvaluateFormula
节点说明： 读取公式 cell 的「上次计算结果」。注意：exceljs 不会重新计算公式，只能读出文件里上次 Excel 保存时缓存的 result。如果刚 SetFormula 还没用 Excel 打开过，evaluated 会是 false。
XML 示例：

<EvaluateFormula handle="" sheet="" cell="A1" outKey="formulaResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
单元格	`cell`	string	是	-	A1
输出变量名	`outKey`	output	否	`formulaResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`formulaResult`	object	{ ok:true, data:{ sheet, address, formula, result, evaluated }, … }

文本转数字（Excel）

节点标识： TextToNumber
节点说明： 把区域内「看起来像数字的字符串」转成真数值。支持 “1,234.56” 千位分隔，自动去掉 numFmt=”@”。
XML 示例：

<TextToNumber handle="" sheet="" range="B2:B100" outKey="textToNumberResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
区域	`range`	string	是	-	B2:B100
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`textToNumberResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`textToNumberResult`	object	{ ok:true, data:{ sheet, range, convertedCells, skippedCells }, … }

数字转文本（Excel）

节点标识： NumberToText
节点说明： 把区域内的数字 / 日期转成字符串，同时把 numFmt 设为 ”@”。
XML 示例：

<NumberToText handle="" sheet="" range="B2:B100" outKey="numberToTextResult" />

界面名称	代码属性名	类型	必填	默认值
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
区域	`range`	string	是	-
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`numberToTextResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`numberToTextResult`	object	{ ok:true, data:{ sheet, range, convertedCells, skippedCells }, … }

设置日期格式（Excel）

节点标识： SetDateFormat
节点说明： 给区域 cell 设置日期 numFmt（默认 yyyy-mm-dd）。不做「字符串 → Date 类型」转换，请先 SetCell value=new Date(…) 再用本任务。
XML 示例：

<SetDateFormat handle="" sheet="" range="C2:C100" format="yyyy-mm-dd" outKey="setDateFormatResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
区域	`range`	string	是	-
日期格式串	`format`	string	否	`yyyy-mm-dd`	常用：yyyy-mm-dd hh:mm:ss / yyyy/m/d / m/d/yyyy / yyyy年m月d日
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`setDateFormatResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`setDateFormatResult`	object	{ ok:true, data:{ sheet, range, format, affectedCells }, … }

设置单元格样式（Excel）

节点标识： SetCellFormat
节点说明： 通用样式入口：numFmt + font(bold/italic/size/color/name) + alignment(horizontal/vertical/wrapText) + fill(color/pattern)。color 接受 “#FF0000” 或 ARGB 8 位。
XML 示例：

<SetCellFormat handle="" sheet="" range="A1:E1" font='&#123;"bold":true,"color":"#FFFFFF"&#125;' fill='&#123;"color":"#1F77B4"&#125;' alignment='&#123;"horizontal":"center"&#125;' outKey="setCellFormatResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
区域	`range`	string	是	-
数字格式	`numFmt`	string	否	-	如 0.00 / @ / 0.00% / yyyy-mm-dd
font 样式 (JSON)	`font`	json	否	-	{“bold”:true,“size”:12,“color”:“#000000”}
alignment 样式 (JSON)	`alignment`	json	否	-	{“horizontal”:“center”,“vertical”:“middle”,“wrapText”:true}
fill 样式 (JSON)	`fill`	json	否	-	{“color”:“#1F77B4”}
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`setCellFormatResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`setCellFormatResult`	object	{ ok:true, data:{ sheet, range, affectedCells, applied:{numFmt?,font?,alignment?,fill?} }, … }

设置筛选（Excel）

节点标识： SetFilter
节点说明： 在数据区域上设置 autoFilter，并按 filters 条件（多条件 AND）隐藏不匹配的数据行（首行视为表头）。op 支持 eq/ne/gt/gte/lt/lte/contains/startsWith/endsWith/in/notIn/empty/notEmpty。
XML 示例：

<SetFilter handle="" sheet="" range="A1:F100" filters='[&#123;"column":"C","op":"eq","value":"待处理"&#125;]' outKey="setFilterResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
数据区域（含表头）	`range`	string	是	-	A1:F100
筛选条件 (JSON 数组)	`filters`	json	是	-	[{“column”:“C”,“op”:“in”,“value”:[“待处理”,“进行中”]}]
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`setFilterResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`setFilterResult`	object	{ ok:true, data:{ sheet, range, hiddenRows, visibleRows, rules }, … }

清除筛选（Excel）

节点标识： ClearFilter
节点说明： 清掉 worksheet 的 autoFilter，并把所有 row.hidden 设回 false。
XML 示例：

<ClearFilter handle="" sheet="" outKey="clearFilterResult" />

界面名称	代码属性名	类型	必填	默认值
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`clearFilterResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`clearFilterResult`	object	{ ok:true, data:{ sheet, restoredRows }, … }

读取可见行（Excel）

节点标识： GetFilteredRows
节点说明： 返回 sheet 中所有 hidden=false 的行数据（跳过隐藏行）。常和 SetFilter 配对使用。
XML 示例：

<GetFilteredRows handle="" sheet="" range="A1:F100" outKey="visibleRows" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
数据区域	`range`	string	否	-	缺省取整个 worksheet
返回表头行	`includeHeader`	boolean	否	`true`
输出变量名	`outKey`	output	否	`visibleRows`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`visibleRows`	object	{ ok:true, data:{ sheet, range, headerRow?, rows:二维数组, total }, … }

追加行（Excel）

节点标识： AppendRow
节点说明： 把一行 / 多行数据追加到 sheet 已用区域末尾，自动定位末尾行。values 支持一维数组（单行）、二维数组（多行）、对象（按表头映射列）、对象数组。对象模式下若表头行为空，默认用对象 key 自动写表头。最常用于「采集一条数据写到结果表」。
XML 示例：

<AppendRow handle="" sheet="" values="[1,2,3]" outKey="appendRowResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
追加数据	`values`	json	是	-	一维数组=单行；二维数组=多行；对象/对象数组=按表头映射列
表头所在行	`headerRow`	number	否	`1`	仅对象模式生效：据此行表头决定每个 key 落到哪一列
表头为空时自动写表头	`writeHeaderIfEmpty`	boolean	否	`true`	仅对象模式生效：表头行为空时用对象 key 自动写一行表头
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`appendRowResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`appendRowResult`	object	{ ok:true, data:{ sheet, startRow, appendedRows, cols, range }, … }

插入行（Excel）

节点标识： InsertRows
节点说明： 在 beforeRow 之前插入 count 个空行。exceljs spliceRows 会自动 shift 后续行与公式。
XML 示例：

<InsertRows handle="" sheet="" beforeRow="3" count="1" outKey="insertRowsResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
插入位置（1-indexed）	`beforeRow`	number	是	-	3
数量	`count`	number	否	`1`
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`insertRowsResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`insertRowsResult`	object	{ ok:true, data:{ sheet, beforeRow, count }, … }

删除行（Excel）

节点标识： DeleteRows
节点说明： 从 startRow 起删 count 行。
XML 示例：

<DeleteRows handle="" sheet="" startRow="3" count="1" outKey="deleteRowsResult" />

界面名称	代码属性名	类型	必填	默认值
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
起始行（1-indexed）	`startRow`	number	是	-
数量	`count`	number	否	`1`
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`deleteRowsResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`deleteRowsResult`	object	{ ok:true, data:{ sheet, startRow, count, removed }, … }

插入列（Excel）

节点标识： InsertColumns
节点说明： 在 beforeColumn 之前插入 count 个空列。
XML 示例：

<InsertColumns handle="" sheet="" beforeColumn="C" count="1" outKey="insertColumnsResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
插入位置（列字母或 1-indexed）	`beforeColumn`	string	是	-	C 或 3
数量	`count`	number	否	`1`
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`insertColumnsResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`insertColumnsResult`	object	{ ok:true, data:{ sheet, beforeColumn, count }, … }

删除列（Excel）

节点标识： DeleteColumns
节点说明： 从 startColumn 起删 count 列。
XML 示例：

<DeleteColumns handle="" sheet="" startColumn="C" count="1" outKey="deleteColumnsResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
起始列（字母或 1-indexed）	`startColumn`	string	是	-	C 或 3
数量	`count`	number	否	`1`
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`deleteColumnsResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`deleteColumnsResult`	object	{ ok:true, data:{ sheet, startColumn, count, removed }, … }

删除重复行（Excel）

节点标识： RemoveDuplicateRows
节点说明： 删除重复行（保留首次出现），删除的是整行（含区域外的列一并上移）。hasHeader=true 时首行表头不参与判重且始终保留。columns 指定判重依据的列（绝对列，如 “A,C”），缺省按区域内所有列判重。
XML 示例：

<RemoveDuplicateRows handle="" sheet="" range="" hasHeader="true" columns="" outKey="removeDuplicateResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
数据区域	`range`	string	否	-	缺省取整个已用区域
首行为表头	`hasHeader`	boolean	否	`true`
判重依据列	`columns`	string	否	-	绝对列，逗号分隔，如 A,C 或 1,3；缺省用区域内所有列
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`removeDuplicateResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`removeDuplicateResult`	object	{ ok:true, data:{ sheet, removed, kept, removedRows:[行号…] }, … }

区域排序（Excel）

节点标识： SortRange
节点说明： 对区域按一个或多个列排序（整行搬运）。hasHeader=true 时首行表头保持在顶部。sortBy 为 JSON 数组，column 为绝对列（字母或数字），order asc/desc，numeric=true 按数值比。空白单元格升降序都沉底。⚠️ range 必须覆盖数据的所有列，否则区域外的列不会跟着重排会导致行内错位；公式列排序后相对引用不会重新调整，排序键建议用静态值。不迁移逐行样式 / 行高。
XML 示例：

<SortRange handle="" sheet="" range="A1:F100" hasHeader="true" sortBy='[&#123;"column":"B","order":"desc","numeric":true&#125;]' outKey="sortResult" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-
数据区域	`range`	string	是	-	A1:F100
首行为表头	`hasHeader`	boolean	否	`true`
排序规则 (JSON 数组)	`sortBy`	json	是	-	[{“column”:“B”,“order”:“desc”,“numeric”:true}]
transient 模式自动保存	`autoSave`	boolean	否	`true`
输出变量名	`outKey`	output	否	`sortResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`sortResult`	object	{ ok:true, data:{ sheet, range, sortedRows, sortBy }, … }

xlsx 转 CSV（Excel）

节点标识： XlsxToCsv
节点说明： 把工作簿的某个 sheet 导出为 CSV。支持 utf8 / utf8-bom 编码、自定义分隔符；visibleOnly=true 时跳过筛选隐藏行。
XML 示例：

<XlsxToCsv filePath="" sheet="" csvPath="" encoding="utf8" delimiter="," visibleOnly="false" outKey="csvFile" />

界面名称	代码属性名	类型	必填	默认值	说明
工作簿 handle	`handle`	string	否	-
源 Excel 文件路径	`filePath`	string	否	-
Sheet	`sheet`	string	否	-	缺省取第 1 个 sheet
输出 CSV 路径	`csvPath`	string	是	-	/path/to/output.csv
编码	`encoding`	select	否	`utf8`
分隔符	`delimiter`	string	否	`,`	默认逗号；Tab 分隔填 \t
只导出可见行	`visibleOnly`	boolean	否	-	true 时跳过 row.hidden=true 的行，常用于 SetFilter 后导出筛选结果
输出变量名	`outKey`	output	否	`csvFile`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`csvFile`	object	{ ok:true, data:{ csvPath, sheet, rows, encoding, visibleOnly }, … }

CSV 转 xlsx（Excel）

节点标识： CsvToXlsx
节点说明： 把 CSV 文件转成 xlsx。内置 RFC 4180 解析器，支持引号转义。hasHeader=true 时把首行设为粗体。
XML 示例：

<CsvToXlsx csvPath="" xlsxPath="" sheetName="Sheet1" delimiter="," hasHeader="false" outKey="xlsxFile" />

界面名称	代码属性名	类型	必填	默认值	说明
源 CSV 路径	`csvPath`	string	是	-
输出 xlsx 路径	`xlsxPath`	string	是	-
Sheet 名	`sheetName`	string	否	`Sheet1`
分隔符	`delimiter`	string	否	`,`
编码	`encoding`	string	否	`utf8`	暂仅支持 utf8（含 BOM 自动剥）
首行表头（加粗）	`hasHeader`	boolean	否	-
输出变量名	`outKey`	output	否	`xlsxFile`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`xlsxFile`	object	{ ok:true, data:{ xlsxPath, sheetName, rows, cols }, … }

成功标准

节点运行状态为成功。
输出变量中包含预期字段，且可被下游节点引用。
对外部系统有写入动作的节点，目标系统中的数据状态与配置一致。

失败排查

现象 / 报错	可能原因	处理建议
找不到插件分组	插件未安装、未加载或当前端不是桌面客户端	在「扩展能力」中刷新/重新扫描插件，必要时重启客户端。
连接或鉴权失败	连接配置缺失、令牌过期或权限不足	重新配置连接，确认账号具备对应资源权限。
查询结果为空	筛选条件过窄、目标资源为空或页面状态不正确	放宽条件，检查资源 ID、日期范围和页面登录态。
写入类操作失败	参数格式不符合平台要求或目标资源不可写	先用少量测试数据验证，再检查必填字段、ID 和权限。

本地 Excel 文件

先选使用方式

什么时候用？

使用前确认

节点总览

节点参数与输出

新建工作簿（Excel）

打开工作簿（Excel）

关闭工作簿（Excel）

保存工作簿（Excel）

列出 Sheet 页（Excel）

新建 Sheet 页（Excel）

重命名 Sheet 页（Excel）

复制 Sheet 页（Excel）

读取单元格（Excel）

写入单元格（Excel）

读取区域（Excel）

写入区域（Excel）

读取已用区域信息（Excel）

查找单元格（Excel）

清空单元格 / 区域（Excel）

合并 / 拆分单元格（Excel）

写入公式（Excel）

公式向下填充（Excel）

公式向右填充（Excel）

读取公式结果（Excel）

文本转数字（Excel）

数字转文本（Excel）

设置日期格式（Excel）

设置单元格样式（Excel）

设置筛选（Excel）

清除筛选（Excel）

读取可见行（Excel）

追加行（Excel）

插入行（Excel）

删除行（Excel）

插入列（Excel）

删除列（Excel）

删除重复行（Excel）

区域排序（Excel）

xlsx 转 CSV（Excel）

CSV 转 xlsx（Excel）

成功标准

失败排查

相关说明