飞书电子表格

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

插件标识：rpa-plugin-feishu-sheets
插件分类：办公协同插件
节点数量：10 个

先选使用方式

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

什么时候用？

覆盖飞书电子表格（Spreadsheet）全套原子节点：连通性 / sheet 增删查 / 区域读写 / 行追加 / 行列增删。复用 feishu-app 连接（App ID + App Secret），节点通过 connectionId 引用即可，无需手动管理 tenant_access_token。
需要在自动化流程中复用该插件提供的读取、写入、同步或处理能力。

使用前确认

需要先配置连接：feishu-app。
办公协同类能力需要确认文件、表格、空间或数据库的访问权限。
建议先运行连通性、查询或只读节点，确认权限和参数正确后再执行写入类节点。

连接配置

连接类型	名称	说明
`feishu-app`	feishu-app	通过 App ID + App Secret 调用飞书电子表格 OpenAPI（与多维表共享同一连接）

节点总览

节点名称	节点标识	说明
连通性测试（飞书电子表格）	`FeishuSheetsPing`	向飞书 OpenAPI 换一次 tenant_access_token 验证 App ID/App Secret 凭据可用
列出 Sheet 页（飞书电子表格）	`ListFeishuSheets`	列出指定 spreadsheet 下所有 sheet 页（sheetId + title + index + 行列数）
获取 Sheet 元信息（飞书电子表格）	`GetFeishuSheetMeta`	获取指定 sheet 的行列总数（gridRowCount/gridColumnCount = 网格上限，非数据范围）、隐藏状态、index 等
新建 Sheet 页（飞书电子表格）	`CreateFeishuSheet`	在指定 spreadsheet 下新建一个 sheet 页
删除 Sheet 页（飞书电子表格）	`DeleteFeishuSheet`	删除指定 sheet 页（强校验：sheet 必须存在）
读取区域数据（飞书电子表格）	`GetFeishuSheetRange`	读取 sheet 上一个区域的数据。支持 CELL / ROW / COLUMN / RANGE 四种 dim，valueRenderOption 控制公式 / 显示值
写入区域数据（飞书电子表格）	`SetFeishuSheetRange`	向 sheet 区域写入数据（PUT 覆盖式）。dim=CELL/ROW/COLUMN 时根据 values 自动展开范围
追加行（飞书电子表格）	`AppendFeishuSheetRow`	在 sheet 末尾追加一行或多行（飞书自动找末尾）
插入行 / 列（飞书电子表格）	`InsertFeishuSheetRowsOrColumns`	在指定位置之前插入若干行或列。index 用户视角 1-indexed，插件自动转 0-indexed 传给飞书 API
删除行 / 列（飞书电子表格）	`DeleteFeishuSheetRowsOrColumns`	删除指定位置开始的若干行或列。index 用户视角 1-indexed

节点参数与输出

连通性测试（飞书电子表格）

节点标识： FeishuSheetsPing
节点说明： 向飞书 OpenAPI 换一次 tenant_access_token 验证 App ID/App Secret 凭据可用
XML 示例：

<FeishuSheetsPing connectionId="" outKey="pingResult" />

界面名称	代码属性名	类型	必填	默认值	说明
飞书连接	`connectionId`	connection	是	-	在「连接管理」配置的飞书自建应用连接
输出变量名	`outKey`	output	否	`pingResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`pingResult`	object	{ ok:true, data:{ message }, statusCode, attempts, durationMs } 或 { ok:false, error, code, category, hint? }

列出 Sheet 页（飞书电子表格）

节点标识： ListFeishuSheets
节点说明： 列出指定 spreadsheet 下所有 sheet 页（sheetId + title + index + 行列数）
XML 示例：

<ListFeishuSheets connectionId="" url="" outKey="sheets" />

界面名称	代码属性名	类型	必填	默认值	说明
飞书连接	`connectionId`	connection	是	-
电子表格链接	`url`	string	否	-	粘贴 https://xxx.feishu.cn/sheets/<token>；与 spreadsheetToken 二选一
spreadsheetToken（替代 url）	`spreadsheetToken`	string	否	-	直接传 spreadsheet token；不填则从 url 解析
输出变量名	`outKey`	output	否	`sheets`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`sheets`	object	{ ok:true, data:{ sheets:[{ sheetId, title, index, hidden, resourceType, rowCount?, columnCount? }], total }, … }

获取 Sheet 元信息（飞书电子表格）

节点标识： GetFeishuSheetMeta
节点说明： 获取指定 sheet 的行列总数（gridRowCount/gridColumnCount = 网格上限，非数据范围）、隐藏状态、index 等
XML 示例：

<GetFeishuSheetMeta connectionId="" url="" sheetIdOrName="" outKey="sheetMeta" />

界面名称	代码属性名	类型	必填	默认值	说明
飞书连接	`connectionId`	connection	是	-
电子表格链接	`url`	string	否	-
spreadsheetToken（替代 url）	`spreadsheetToken`	string	否	-
Sheet（ID 或名称）	`sheetIdOrName`	string	否	-	缺省取激活页 = 列表第 1 个 sheet
输出变量名	`outKey`	output	否	`sheetMeta`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`sheetMeta`	object	{ ok:true, data:{ sheetId, title, index, hidden, resourceType, rowCount, columnCount, gridRowCount, gridColumnCount }, … } — gridRowCount/gridColumnCount 为网格上限，不要拿来做 append 起点；append 请用 AppendFeishuSheetRows

新建 Sheet 页（飞书电子表格）

节点标识： CreateFeishuSheet
节点说明： 在指定 spreadsheet 下新建一个 sheet 页
XML 示例：

<CreateFeishuSheet connectionId="" url="" name="" outKey="newSheet" />

界面名称	代码属性名	类型	必填	默认值	说明
飞书连接	`connectionId`	connection	是	-
电子表格链接	`url`	string	否	-
spreadsheetToken（替代 url）	`spreadsheetToken`	string	否	-
新 Sheet 名称	`name`	string	是	-	销售明细
插入位置 (0-indexed)	`index`	number	否	-	缺省追加到末尾；填 0 表示插到最前
输出变量名	`outKey`	output	否	`newSheet`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`newSheet`	object	{ ok:true, data:{ sheetId, title, index }, … }

删除 Sheet 页（飞书电子表格）

节点标识： DeleteFeishuSheet
节点说明： 删除指定 sheet 页（强校验：sheet 必须存在）
XML 示例：

<DeleteFeishuSheet connectionId="" url="" sheetIdOrName="" outKey="deletedSheet" />

界面名称	代码属性名	类型	必填	默认值
飞书连接	`connectionId`	connection	是	-
电子表格链接	`url`	string	否	-
spreadsheetToken（替代 url）	`spreadsheetToken`	string	否	-
要删除的 Sheet（ID 或名称）	`sheetIdOrName`	string	是	-
输出变量名	`outKey`	output	否	`deletedSheet`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`deletedSheet`	object	{ ok:true, data:{ deletedSheetId, deletedSheetTitle? }, … }

读取区域数据（飞书电子表格）

节点标识： GetFeishuSheetRange
节点说明： 读取 sheet 上一个区域的数据。支持 CELL / ROW / COLUMN / RANGE 四种 dim，valueRenderOption 控制公式 / 显示值
XML 示例：

<GetFeishuSheetRange connectionId="" url="" sheetIdOrName="" range="A1:C10" dim="RANGE" outKey="rangeData" />

界面名称	代码属性名	类型	必填	默认值	说明
飞书连接	`connectionId`	connection	是	-
电子表格链接	`url`	string	否	-
spreadsheetToken（替代 url）	`spreadsheetToken`	string	否	-
Sheet（ID 或名称）	`sheetIdOrName`	string	否	-	缺省取激活页
区域 / 行 / 列	`range`	string	是	-	RANGE=A1:C10；CELL=A1；ROW=3 或 A3（默认取 A:ZZ）；COLUMN=B 或 2（默认取 1~10000 行）
读取维度	`dim`	select	否	`RANGE`
渲染方式	`valueRenderOption`	select	否	`FormattedValue`
日期时间渲染	`dateTimeRenderOption`	select	否	-
补齐稀疏矩阵	`densify`	boolean	否	-	默认：RANGE/CELL 补齐到请求 range 形状，ROW/COLUMN 保留飞书原始稀疏结构，避免整行/整列产生巨大 null 矩阵；显式设 true 可强制补齐
输出变量名	`outKey`	output	否	`rangeData`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`rangeData`	object	{ ok:true, data:{ range, dim, values, revision? }, … }；values 是二维数组。RANGE/CELL 默认补齐空位为 null；ROW/COLUMN 默认保留原始稀疏结构

写入区域数据（飞书电子表格）

节点标识： SetFeishuSheetRange
节点说明： 向 sheet 区域写入数据（PUT 覆盖式）。dim=CELL/ROW/COLUMN 时根据 values 自动展开范围
XML 示例：

<SetFeishuSheetRange connectionId="" url="" sheetIdOrName="" range="A1" dim="RANGE" values="[[1,2],[3,4]]" outKey="writeResult" />

界面名称	代码属性名	类型	必填	默认值	说明
飞书连接	`connectionId`	connection	是	-
电子表格链接	`url`	string	否	-
spreadsheetToken（替代 url）	`spreadsheetToken`	string	否	-
Sheet（ID 或名称）	`sheetIdOrName`	string	否	-
区域 / 行 / 列 / 起点	`range`	string	是	-	RANGE 模式下传起点 A1；CELL=A1；ROW=3 或 A3；COLUMN=B 或 2
写入维度	`dim`	select	否	`RANGE`
写入数据	`values`	json	是	-	CELL=标量；ROW/COLUMN=一维数组；RANGE=二维数组。也可传 JSON 字符串或逗号分隔
输出变量名	`outKey`	output	否	`writeResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`writeResult`	object	{ ok:true, data:{ range, dim, written:{ rows, cols, cells }, revision? }, … }

追加行（飞书电子表格）

节点标识： AppendFeishuSheetRow
节点说明： 在 sheet 末尾追加一行或多行（飞书自动找末尾）
XML 示例：

<AppendFeishuSheetRow connectionId="" url="" sheetIdOrName="" values="[\"a\",\"b\",\"c\"]" beginColumn="A" outKey="appendResult" />

界面名称	代码属性名	类型	必填	默认值	说明
飞书连接	`connectionId`	connection	是	-
电子表格链接	`url`	string	否	-
spreadsheetToken（替代 url）	`spreadsheetToken`	string	否	-
Sheet（ID 或名称）	`sheetIdOrName`	string	否	-
追加数据	`values`	json	是	-	一维=单行；二维=多行；如 [“a”, 1, “2025-01-01”] 或 [[“a”,1],[“b”,2]]
起始列	`beginColumn`	string	否	`A`	字母（A / AB）或数字（1 / 27）
插入模式	`insertDataOption`	select	否	`INSERT_ROWS`
输出变量名	`outKey`	output	否	`appendResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`appendResult`	object	{ ok:true, data:{ appendedRows, cellCount, range, revision? }, … }

插入行 / 列（飞书电子表格）

节点标识： InsertFeishuSheetRowsOrColumns
节点说明： 在指定位置之前插入若干行或列。index 用户视角 1-indexed，插件自动转 0-indexed 传给飞书 API
XML 示例：

<InsertFeishuSheetRowsOrColumns connectionId="" url="" sheetIdOrName="" mode="ROW" index="3" count="1" outKey="insertResult" />

界面名称	代码属性名	类型	必填	默认值	说明
飞书连接	`connectionId`	connection	是	-
电子表格链接	`url`	string	否	-
spreadsheetToken（替代 url）	`spreadsheetToken`	string	否	-
Sheet（ID 或名称）	`sheetIdOrName`	string	否	-
模式	`mode`	select	否	`ROW`
插入位置（1-indexed）	`index`	string	是	-	mode=ROW 时填行号（3 表示在第 3 行之前插入）；mode=COLUMN 时填列号或列名（B / 2）
数量	`count`	number	否	`1`
继承样式	`inheritStyle`	select	否	-
输出变量名	`outKey`	output	否	`insertResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`insertResult`	object	{ ok:true, data:{ mode, startIndex0, endIndex0, count, inheritStyle? }, … }；startIndex0/endIndex0 是实际传给 API 的 0-indexed 位置

删除行 / 列（飞书电子表格）

节点标识： DeleteFeishuSheetRowsOrColumns
节点说明： 删除指定位置开始的若干行或列。index 用户视角 1-indexed
XML 示例：

<DeleteFeishuSheetRowsOrColumns connectionId="" url="" sheetIdOrName="" mode="ROW" index="3" count="1" outKey="deleteRangeResult" />

界面名称	代码属性名	类型	必填	默认值	说明
飞书连接	`connectionId`	connection	是	-
电子表格链接	`url`	string	否	-
spreadsheetToken（替代 url）	`spreadsheetToken`	string	否	-
Sheet（ID 或名称）	`sheetIdOrName`	string	否	-
模式	`mode`	select	否	`ROW`
删除起点（1-indexed）	`index`	string	是	-	mode=ROW 时填行号；mode=COLUMN 时填列号或列名
数量	`count`	number	否	`1`
输出变量名	`outKey`	output	否	`deleteRangeResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`deleteRangeResult`	object	{ ok:true, data:{ mode, startIndex0, endIndex0, count }, … }

成功标准

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

失败排查

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

飞书电子表格

先选使用方式

什么时候用？

使用前确认

连接配置

节点总览

节点参数与输出

连通性测试（飞书电子表格）

列出 Sheet 页（飞书电子表格）

获取 Sheet 元信息（飞书电子表格）

新建 Sheet 页（飞书电子表格）

删除 Sheet 页（飞书电子表格）

读取区域数据（飞书电子表格）

写入区域数据（飞书电子表格）

追加行（飞书电子表格）

插入行 / 列（飞书电子表格）

删除行 / 列（飞书电子表格）

成功标准

失败排查

相关说明