钉钉在线表格

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

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

先选使用方式

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

什么时候用？

• 覆盖钉钉在线表格（Spreadsheet / Workbook）全套原子节点：连通性 / sheet 增删查 / 区域读写 / 行追加 / 行列增删。复用 dingtalk-app 连接（AppKey + AppSecret + 操作人 unionId/userId），节点通过 connectionId 引用即可，无需手动管理 accessToken / operatorId。
• 需要在自动化流程中复用该插件提供的读取、写入、同步或处理能力。

使用前确认

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

连接配置

连接类型	名称	说明
dingtalk-app	dingtalk-app	通过 AppKey + AppSecret 调用钉钉在线表格 OpenAPI（与多维表共享同一连接）

节点总览

节点名称	节点标识	说明
连通性测试（钉钉在线表格）	DingtalkSheetsPing	向钉钉 OpenAPI 换一次 accessToken 验证 AppKey/AppSecret 凭据可用
列出 Sheet 页（钉钉在线表格）	ListDingtalkSheets	列出指定工作簿下所有 sheet 页（id + name）
获取 Sheet 元信息（钉钉在线表格）	GetDingtalkSheetMeta	获取指定 sheet 的行列总数、最后非空行列、隐藏状态，以及便利字段 firstFreeRow / firstFreeColumn
新建 Sheet 页（钉钉在线表格）	CreateDingtalkSheet	在指定工作簿下新建一个 sheet 页
删除 Sheet 页（钉钉在线表格）	DeleteDingtalkSheet	删除指定 sheet 页（强校验：sheet 必须存在） 注意：删除 Sheet 页不可恢复，请确认 sheetIdOrName 无误。
读取区域数据（钉钉在线表格）	GetDingtalkSheetRange	读取 sheet 上一个区域的数据。支持 CELL / ROW / COLUMN / RANGE 四种 dim，select 可选 values / formulas / displayValues
写入区域数据（钉钉在线表格）	SetDingtalkSheetRange	向 sheet 区域写入数据（PUT 覆盖式）。dim=CELL/ROW/COLUMN 时根据 values 自动展开范围
追加一行（钉钉在线表格）	AppendDingtalkSheetRow	在 sheet 末尾自动追加一行数据（基于 lastNonEmptyRow 计算位置）
插入行 / 列（钉钉在线表格）	InsertDingtalkSheetRowsOrColumns	在指定位置之前插入若干行或列。index 用户视角 1-indexed（行号 / 列号或列名），插件自动转 0-indexed 传给钉钉 API
删除行 / 列（钉钉在线表格）	DeleteDingtalkSheetRowsOrColumns	删除指定位置开始的若干行或列。index 用户视角 1-indexed 注意：删除行/列不可恢复，并会影响后续单元格位置，请确认 index/count 无误。

节点参数与输出

连通性测试（钉钉在线表格）

• 节点标识： DingtalkSheetsPing
• 节点说明： 向钉钉 OpenAPI 换一次 accessToken 验证 AppKey/AppSecret 凭据可用
• XML 示例：

<DingtalkSheetsPing 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 页（钉钉在线表格）

• 节点标识： ListDingtalkSheets
• 节点说明： 列出指定工作簿下所有 sheet 页（id + name）
• XML 示例：

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

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
工作簿链接	url	string	否	-	粘贴 https://alidocs.dingtalk.com/i/nodes/<workbookId>；与 workbookId 二选一
workbookId（替代 url）	workbookId	string	否	-	直接传工作簿 ID；不填则从 url 解析
操作人 unionId（覆盖连接默认值）	operatorUnionId	string	否	-
操作人 userId（覆盖连接默认值）	operatorUserId	string	否	-
输出变量名	outKey	output	否	sheets
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
sheets	object	{ ok:true, data:{ sheets:[{id, name}], total }, statusCode, attempts, durationMs, requestId? }

获取 Sheet 元信息（钉钉在线表格）

• 节点标识： GetDingtalkSheetMeta
• 节点说明： 获取指定 sheet 的行列总数、最后非空行列、隐藏状态，以及便利字段 firstFreeRow / firstFreeColumn
• XML 示例：

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

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
工作簿链接	url	string	否	-	https://alidocs.dingtalk.com/i/nodes/xxxxxxxxxxx
workbookId（替代 url）	workbookId	string	否	-
Sheet（ID 或名称）	sheetIdOrName	string	否	-	缺省取激活页 = 列表第 1 个 sheet
操作人 unionId（覆盖连接默认值）	operatorUnionId	string	否	-
操作人 userId（覆盖连接默认值）	operatorUserId	string	否	-
输出变量名	outKey	output	否	sheetMeta
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
sheetMeta	object	{ ok:true, data:{ id, name, rowCount, columnCount, lastNonEmptyRow, lastNonEmptyColumn, hidden, firstFreeRow, firstFreeColumn }, statusCode, attempts, durationMs, requestId? }

新建 Sheet 页（钉钉在线表格）

• 节点标识： CreateDingtalkSheet
• 节点说明： 在指定工作簿下新建一个 sheet 页
• XML 示例：

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

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
工作簿链接	url	string	否	-
workbookId（替代 url）	workbookId	string	否	-
新 Sheet 名称	name	string	是	-	销售明细
操作人 unionId（覆盖连接默认值）	operatorUnionId	string	否	-
操作人 userId（覆盖连接默认值）	operatorUserId	string	否	-
输出变量名	outKey	output	否	newSheet
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
newSheet	object	{ ok:true, data:{ id, name }, statusCode, attempts, durationMs, requestId? }

删除 Sheet 页（钉钉在线表格）

• 节点标识： DeleteDingtalkSheet
• 节点说明： 删除指定 sheet 页（强校验：sheet 必须存在） 注意：删除 Sheet 页不可恢复，请确认 sheetIdOrName 无误。
• XML 示例：

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

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
工作簿链接	url	string	否	-
workbookId（替代 url）	workbookId	string	否	-
要删除的 Sheet（ID 或名称）	sheetIdOrName	string	是	-
操作人 unionId（覆盖连接默认值）	operatorUnionId	string	否	-
操作人 userId（覆盖连接默认值）	operatorUserId	string	否	-
输出变量名	outKey	output	否	deletedSheet
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
deletedSheet	object	{ ok:true, data:{ deletedSheetId, deletedSheetName? }, statusCode, attempts, durationMs, requestId? }

读取区域数据（钉钉在线表格）

• 节点标识： GetDingtalkSheetRange
• 节点说明： 读取 sheet 上一个区域的数据。支持 CELL / ROW / COLUMN / RANGE 四种 dim，select 可选 values / formulas / displayValues
• XML 示例：

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

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
工作簿链接	url	string	否	-
workbookId（替代 url）	workbookId	string	否	-
Sheet（ID 或名称）	sheetIdOrName	string	否	-	缺省取激活页
区域 / 行 / 列	range	string	是	-	RANGE=A1:C10；CELL=A1；ROW=3 或 A3；COLUMN=B 或 2
读取维度	dim	select	否	RANGE
返回字段	select	select	否	values
操作人 unionId（覆盖连接默认值）	operatorUnionId	string	否	-
操作人 userId（覆盖连接默认值）	operatorUserId	string	否	-
输出变量名	outKey	output	否	rangeData
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
rangeData	object	{ ok:true, data:{ range, dim, select, values }, statusCode, attempts, durationMs, requestId? }；values 形状随 dim 变化（CELL=标量；ROW/COLUMN=一维；RANGE=二维）

写入区域数据（钉钉在线表格）

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

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

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
工作簿链接	url	string	否	-
workbookId（替代 url）	workbookId	string	否	-
Sheet（ID 或名称）	sheetIdOrName	string	否	-
区域 / 行 / 列 / 起点	range	string	是	-	RANGE 模式下传起点 A1 或完整 A1:C10；CELL=A1；ROW=3 或 A3；COLUMN=B 或 2
写入维度	dim	select	否	RANGE
写入数据	values	json	是	-	CELL=标量；ROW/COLUMN=一维数组；RANGE=二维数组。也可传 JSON 字符串或逗号分隔
数字格式（可选）	numberFormat	string	否	-	例如 ”@” 强制文本；”#,##0” 千分位；“General” 默认
操作人 unionId（覆盖连接默认值）	operatorUnionId	string	否	-
操作人 userId（覆盖连接默认值）	operatorUserId	string	否	-
输出变量名	outKey	output	否	writeResult
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
writeResult	object	{ ok:true, data:{ range, dim, written:{rows, cols, cells} }, statusCode, attempts, durationMs, requestId? }

追加一行（钉钉在线表格）

• 节点标识： AppendDingtalkSheetRow
• 节点说明： 在 sheet 末尾自动追加一行数据（基于 lastNonEmptyRow 计算位置）
• XML 示例：

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

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
工作簿链接	url	string	否	-
workbookId（替代 url）	workbookId	string	否	-
Sheet（ID 或名称）	sheetIdOrName	string	否	-
一行数据	values	json	是	-	一维数组；如 [“a”, 1, “2025-01-01”]
起始列	beginColumn	string	否	A	字母（A / AB）或数字（1 / 27）
数字格式（可选）	numberFormat	string	否	-
操作人 unionId（覆盖连接默认值）	operatorUnionId	string	否	-
操作人 userId（覆盖连接默认值）	operatorUserId	string	否	-
输出变量名	outKey	output	否	appendResult
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
appendResult	object	{ ok:true, data:{ appendedRow, range, cellCount }, statusCode, attempts, durationMs, requestId? }

插入行 / 列（钉钉在线表格）

• 节点标识： InsertDingtalkSheetRowsOrColumns
• 节点说明： 在指定位置之前插入若干行或列。index 用户视角 1-indexed（行号 / 列号或列名），插件自动转 0-indexed 传给钉钉 API
• XML 示例：

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

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
工作簿链接	url	string	否	-
workbookId（替代 url）	workbookId	string	否	-
Sheet（ID 或名称）	sheetIdOrName	string	否	-
模式	mode	select	否	ROW
插入位置（1-indexed）	index	string	是	-	mode=ROW 时填行号（3 表示在第 3 行之前插入）；mode=COLUMN 时填列号或列名（B / 2）
数量	count	number	否	1
操作人 unionId（覆盖连接默认值）	operatorUnionId	string	否	-
操作人 userId（覆盖连接默认值）	operatorUserId	string	否	-
输出变量名	outKey	output	否	insertResult
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
insertResult	object	{ ok:true, data:{ mode, atIndex0, count }, statusCode, attempts, durationMs, requestId? }；atIndex0 是实际传给 API 的 0-indexed 位置

删除行 / 列（钉钉在线表格）

• 节点标识： DeleteDingtalkSheetRowsOrColumns
• 节点说明： 删除指定位置开始的若干行或列。index 用户视角 1-indexed 注意：删除行/列不可恢复，并会影响后续单元格位置，请确认 index/count 无误。
• XML 示例：

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

界面名称	代码属性名	类型	必填	默认值	说明
钉钉连接	connectionId	connection	是	-
工作簿链接	url	string	否	-
workbookId（替代 url）	workbookId	string	否	-
Sheet（ID 或名称）	sheetIdOrName	string	否	-
模式	mode	select	否	ROW
删除起点（1-indexed）	index	string	是	-	mode=ROW 时填行号；mode=COLUMN 时填列号或列名
数量	count	number	否	1
操作人 unionId（覆盖连接默认值）	operatorUnionId	string	否	-
操作人 userId（覆盖连接默认值）	operatorUserId	string	否	-
输出变量名	outKey	output	否	deleteRangeResult
失败时抛错	failOnError	boolean	否	true

输出字段：

字段	类型	说明
deleteRangeResult	object	{ ok:true, data:{ mode, atIndex0, count }, statusCode, attempts, durationMs, requestId? }

成功标准

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

失败排查

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

相关说明

• 插件能力由桌面端扩展能力机制加载，和普通后端指令树不是同一数据源。
• 插件页按插件维度整理；每个节点的帮助入口会跳到所属插件页，页面内可查节点标识、参数和输出。