Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/skill-marketplace/tencent-docs-skill
tencent-docs
Unverified腾讯文档(docs.qq.com)-在线云文档平台,是创建、编辑、管理**在线**文档的首选 skill。仅当用户明确指向腾讯文档/在线文档/docs.qq.com,或任务需要在线协作文档时使用;泛指"做个文档/保存成文件/PPT"且未点名在线平台时,默认走本地工具(本地 pptx 技能等),不要误用本 skill。支持能力:(1) 创建各类在线文档(文档/Word/Excel/幻灯片/思维导图/流程图/智能表格/收集表)(2) 管理知识库空间(创建空间、查询空间列表)(3) 管理空间节点、文件夹结构 (4) 读取/搜索文档内容 (5) 编辑操作智能表 (6) 编辑操作在线文档 (7) 文件管理(重命名、移动、删除、复制、导入导出)(8) 网页剪藏、本地文件/html/文档上云。
sheet/api/mcp-api.md
View on GitHub# 腾讯文档 Sheet MCP 工具完整参考
本文件包含腾讯文档 Sheet MCP 所有工具的通用 API 说明、详细调用示例、参数说明和返回值说明。
---
## 通用说明
### 公共参数
所有工具都包含以下公共参数:
- `file_id` (string, 通常必填): 文档唯一标识符;支持 `file_url` 的工具可与 `file_url` 二选一
- `sheet_id` (string, 必填): 子表 ID(部分工具不需要或可选,详见各工具说明)
部分工具支持 `file_url` 与 `file_id` 二选一,具体以各工具参数说明为准。
### 响应结构
除单个工具另有返回值说明外,API 成功时返回空对象 `{}`,失败时会抛出对应错误信息。
## 工具调用示例
## 1. sheet.set_cell_value
### 功能说明
设置在线表格指定单元格的值,支持文本、数字、布尔、公式等类型(SHEET)。
> 💡 **建议**:单次写入操作的请求体内容尽量不超过 **1MB**,超大内容请拆分为多次写入。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"cell": {
"row": 0,
"col": 0,
"value_type": "STRING",
"string_value": "Hello World"
}
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `cell` (object, 必填): 单元格值参数
- `row` (int64, 必填): 行索引(0-based)
- `col` (int64, 必填): 列索引(0-based)
- `value_type` (string, 必填): 值类型,可选值:`STRING`、`NUMBER`、`BOOL`、`FORMULA`
- `number_value` (double, 可选): 数值,`value_type` 为 `NUMBER` 时使用
- `string_value` (string, 可选): 字符串值,`value_type` 为 `STRING` 时使用
- `bool_value` (bool, 可选): 布尔值,`value_type` 为 `BOOL` 时使用
- `formula` (string, 可选): 公式,`value_type` 为 `FORMULA` 时使用,例如 `"=SUM(A1:A10)"`
### 返回值说明
```json
{}
```
---
## 2. sheet.set_range_value
### 功能说明
批量设置在线表格多个单元格的值(SHEET)。
> 💡 **建议**:单次写入操作的请求体内容尽量不超过 **1MB**(大约几千个单元格,视单元格内容长度而定),超大批量请拆分为多次写入。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"values": [
{
"row": 0,
"col": 0,
"value_type": "STRING",
"string_value": "Name"
},
{
"row": 0,
"col": 1,
"value_type": "STRING",
"string_value": "Score"
},
{
"row": 1,
"col": 0,
"value_type": "STRING",
"string_value": "Alice"
},
{
"row": 1,
"col": 1,
"value_type": "NUMBER",
"number_value": 95.5
}
]
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `values` (array, 必填): 单元格值列表,每个元素与 `set_cell_value` 的 `cell` 参数结构相同
### 返回值说明
```json
{}
```
---
## 3. sheet.set_cell_style
### 功能说明
设置在线表格指定范围单元格的样式,包括字体、颜色、对齐等(SHEET)。同时支持三种清除场景:
1. 顶层 `is_clear=true`:清除区域内所有样式(字体/对齐/背景/数字格式等),此时 `format` 字段被忽略。
2. `format` 内字段级清除:`bool` 字段传 `false`、`string` 字段传空字符串 `""`、`int32` 字段传 `0`,均表示清除该单个属性。
3. 未传字段:保持原值不变。
### 调用示例
#### 示例 1:设置样式
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 5,
"end_col": 3,
"format": {
"bold": true,
"italic": false,
"font_size": 12,
"font_color": "FF000000",
"bg_color": "FFFFFF00",
"horizontal_align": "center",
"vertical_align": "center",
"wrap_text": true
}
}
```
#### 示例 2:整体清除区域样式
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 5,
"end_col": 3,
"is_clear": true
}
```
#### 示例 3:只清除背景色 + 取消加粗
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 5,
"end_col": 3,
"format": {
"bold": false,
"bg_color": ""
}
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` (int64, 必填): 起始行索引(0-based)
- `start_col` (int64, 必填): 起始列索引(0-based)
- `end_row` (int64, 必填): 结束行索引
- `end_col` (int64, 必填): 结束列索引
- `is_clear` (bool, 可选): 若为 true 则清除区域内单元格的所有样式,同时忽略 `format` 字段
- `format` (object, 可选): 样式参数对象(`is_clear=true` 时被忽略)
- `bold` (bool, 可选): 是否粗体;传 `false` 表示清除粗体
- `italic` (bool, 可选): 是否斜体;传 `false` 表示清除斜体
- `font_family` (string, 可选): 字体名称;传 `""` 表示清除字体
- `font_size` (int32, 可选): 字号(pt);传 `0` 表示清除字号
- `font_color` (string, 可选): 字体颜色,ARGB hex,如 `"FF000000"`;传 `""` 表示清除字体颜色
- `bg_color` (string, 可选): 背景色,ARGB hex,如 `"FFFFFFFF"`;传 `""` 表示清除背景色
- `horizontal_align` (string, 可选): 水平对齐:`general` / `left` / `center` / `right` / `fill` / `justify`;传 `""` 表示清除水平对齐
- `vertical_align` (string, 可选): 垂直对齐:`top` / `center` / `bottom` / `justify`;传 `""` 表示清除垂直对齐
- `wrap_text` (bool, 可选): 是否自动换行;传 `false` 表示清除自动换行
- `strike_through` (bool, 可选): 是否删除线;传 `false` 表示清除删除线
- `underline` (string, 可选): 下划线类型:`none` / `single` / `double` / `single_accounting` / `double_accounting`;传 `""` 表示清除下划线
- `number_format_pattern` (string, 可选): 数字格式,如 `"0.00%"`;传 `""` 表示清除数字格式
### 返回值说明
```json
{}
```
---
## 4. sheet.merge_cell
### 功能说明
合并在线表格指定范围的单元格,支持全部合并、按行合并、按列合并(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 3,
"end_col": 3,
"merge_type": "all"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` (int64, 必填): 起始行索引(0-based)
- `start_col` (int64, 必填): 起始列索引(0-based)
- `end_row` (int64, 必填): 结束行索引
- `end_col` (int64, 必填): 结束列索引
- `merge_type` (string, 必填): 合并类型
- `"all"`: 全部合并(默认)
- `"columns"`: 按列合并
- `"rows"`: 按行合并
### 返回值说明
```json
{}
```
---
## 5. sheet.insert_dimension
### 功能说明
在在线表格指定位置插入行或列(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"dimension_type": "row",
"index": 2,
"count": 3,
"direction": "before"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `dimension_type` (string, 必填): 行列类型:`"row"` | `"col"`
- `index` (int64, 必填): 起始索引(0-based)
- `count` (int64, 必填): 插入数量
- `direction` (string, 可选): 插入方向:`"before"`(默认)| `"after"`
### 返回值说明
```json
{}
```
---
## 6. sheet.delete_dimension
### 功能说明
删除在线表格指定位置的行或列(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"dimension_type": "col",
"index": 3,
"count": 2
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `dimension_type` (string, 必填): 行列类型:`"row"` | `"col"`
- `index` (int64, 必填): 起始索引(0-based)
- `count` (int64, 必填): 删除数量
### 返回值说明
```json
{}
```
---
## 7. sheet.set_freeze
### 功能说明
设置在线表格的冻结行列数,传 0 可取消冻结(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"row_count": 1,
"col_count": 2
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `row_count` (int64, 必填): 冻结行数(0 = 取消冻结行)
- `col_count` (int64, 必填): 冻结列数(0 = 取消冻结列)
### 返回值说明
```json
{}
```
---
## 8. sheet.set_filter
### 功能说明
为在线表格指定数据区域设置筛选(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 100,
"end_col": 5
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` (int64, 必填): 数据区域起始行(0-based)
- `start_col` (int64, 必填): 数据区域起始列(0-based)
- `end_row` (int64, 必填): 数据区域结束行
- `end_col` (int64, 必填): 数据区域结束列
- `filter_id` (string, 可选): 筛选 ID(不传则自动生成)
### 返回值说明
```json
{}
```
---
## 9. sheet.remove_filter
### 功能说明
移除在线表格的筛选,可按筛选 ID 精确移除或移除全部(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"filter_id": "filter_001"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `filter_id` (string, 可选): 筛选 ID(不传则移除该子表所有筛选)
### 返回值说明
```json
{}
```
---
## 10. sheet.set_link
### 功能说明
为在线表格指定单元格设置超链接,可指定链接 URL 和显示文本(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"row": 0,
"col": 0,
"url": "https://docs.qq.com",
"display_text": "腾讯文档"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `row` (int64, 必填): 单元格行(0-based)
- `col` (int64, 必填): 单元格列(0-based)
- `url` (string, 必填): 超链接 URL
- `display_text` (string, 可选): 单元格显示文本
### 返回值说明
```json
{}
```
---
## 11. sheet.clear_link
### 功能说明
清除在线表格指定单元格的超链接,可按链接 ID 精确清除或清除全部超链接(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"row": 0,
"col": 0,
"link_id": "link_001"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `row` (int64, 必填): 单元格行(0-based)
- `col` (int64, 必填): 单元格列(0-based)
- `link_id` (string, 可选): 链接 ID(不传则按位置清除)
### 返回值说明
```json
{}
```
---
## 12. sheet.unmerge_cell
### 功能说明
取消在线表格指定区域的单元格合并(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 3,
"end_col": 3
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` (int64, 必填): 起始行索引(0-based)
- `start_col` (int64, 必填): 起始列索引(0-based)
- `end_row` (int64, 必填): 结束行索引
- `end_col` (int64, 必填): 结束列索引
### 返回值说明
```json
{}
```
---
## 13. sheet.clear_range_cells
### 功能说明
清除在线表格指定区域内所有单元格的内容,不影响样式(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 9,
"end_col": 4
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` (int64, 必填): 起始行索引(0-based)
- `start_col` (int64, 必填): 起始列索引(0-based)
- `end_row` (int64, 必填): 结束行索引
- `end_col` (int64, 必填): 结束列索引
### 返回值说明
```json
{}
```
---
## 14. sheet.clear_range_style
### 功能说明
清除在线表格指定区域内所有单元格的样式,不影响内容(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 9,
"end_col": 4
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` (int64, 必填): 起始行索引(0-based)
- `start_col` (int64, 必填): 起始列索引(0-based)
- `end_row` (int64, 必填): 结束行索引
- `end_col` (int64, 必填): 结束列索引
### 返回值说明
```json
{}
```
---
## 15. sheet.clear_range_all
### 功能说明
清空在线表格指定区域内所有单元格的内容和样式(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 9,
"end_col": 4
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` (int64, 必填): 起始行索引(0-based)
- `start_col` (int64, 必填): 起始列索引(0-based)
- `end_row` (int64, 必填): 结束行索引
- `end_col` (int64, 必填): 结束列索引
### 返回值说明
```json
{}
```
---
## 16. sheet.unset_freeze
### 功能说明
删除在线表格指定子表的所有冻结行列(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
### 返回值说明
```json
{}
```
---
## 17. sheet.get_sheet_info
### 功能说明
获取在线表格的子表信息,包括子表 ID、名称、类型、行列数量(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
> 注意:此工具不需要 `sheet_id` 参数,返回文档下所有子表的信息。
### 返回值说明
```json
{
"sheets": [
{
"sheet_id": "sub_sheet_001",
"sheet_name": "Sheet1",
"sheet_type": "worksheet",
"row_count": 100,
"col_count": 26
}
]
}
```
- `sheets` (array): 子表信息列表
- `sheet_id` (string): 子表 ID
- `sheet_name` (string): 子表名称
- `sheet_type` (string): 子表类型:`worksheet` / `smartsheet` / `smartcanvas`
- `row_count` (int32): 行数
- `col_count` (int32): 列数
---
## 18. sheet.get_cell_data
### 功能说明
获取在线表格指定区域的单元格数据,支持返回 CSV 格式或结构化单元格数据(SHEET)。
> ⚠️ **限制**:单次请求的单元格范围不得超过 **20000** 个(即 `(end_row - start_row + 1) × (end_col - start_col + 1) ≤ 20000`),超出将返回错误。如需获取更大范围的数据,请分多次请求。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 9,
"end_col": 4,
"return_csv": false
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` (int64, 必填): 起始行索引(0-based)
- `start_col` (int64, 必填): 起始列索引(0-based)
- `end_row` (int64, 必填): 结束行索引
- `end_col` (int64, 必填): 结束列索引
- `return_csv` (bool, 可选): 是否以 CSV 格式返回数据,`true` 返回 `csv_data`,`false` 返回 `cells` 结构化数据(默认 `false`)
### 返回值说明
```json
{
"csv_data": "Name,Score\nAlice,95.5\n",
"cells": [
{
"row": 0,
"col": 0,
"value_type": "STRING",
"string_value": "Name"
},
{
"row": 0,
"col": 1,
"value_type": "STRING",
"string_value": "Score"
}
]
}
```
- `csv_data` (string): CSV 格式数据(`return_csv=true` 时返回)
- `cells` (array): 结构化单元格数据(`return_csv=false` 时返回)
- `row` (int32): 行索引(0-based)
- `col` (int32): 列索引(0-based)
- `value_type` (string): 值类型:`NUMBER` / `STRING` / `BOOL` / `FORMULA` / `ERROR` / `TIME_STRING` / `RICH_STRING`
- `number_value` (double): 数值
- `string_value` (string): 字符串值
- `bool_value` (bool): 布尔值
- `formula` (string): 公式
---
## 19. sheet.get_merged_cells
### 功能说明
获取在线表格指定区域内与该区域相交的合并单元格信息,返回合并单元格范围列表(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 9,
"end_col": 9
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` (int64, 必填): 查询区域起始行索引(0-based)
- `start_col` (int64, 必填): 查询区域起始列索引(0-based)
- `end_row` (int64, 必填): 查询区域结束行索引
- `end_col` (int64, 必填): 查询区域结束列索引
### 返回值说明
```json
{
"merged_cells": [
"sub_sheet_001$A1:B2",
"sub_sheet_001$C3:D5"
]
}
```
- `merged_cells` (array): 与查询区域相交的合并单元格范围列表,格式为 `"SheetID$A1:B2"`(列使用字母表示,A=第0列,B=第1列,以此类推)
---
## 20. sheet.set_dimension_size
### 功能说明
设置在线表格指定行的行高或指定列的列宽,支持批量设置和清除自定义尺寸恢复默认值(SHEET)。支持两种模式:单个设置(使用 `index`)和批量设置(使用 `start_index` + `end_index`)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"dimensions": [
{
"dimension_type": "row",
"index": 0,
"size": 40
},
{
"dimension_type": "col",
"start_index": 2,
"end_index": 5,
"size": 120
},
{
"dimension_type": "row",
"index": 5,
"is_clear": true
}
]
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `dimensions` (array, 必填): 行高/列宽参数列表,每个元素包含:
- `dimension_type` (string, 必填): 行列类型:`"row"` | `"col"`
- `index` (int64, 可选): 行或列的索引(0-based),设置单个行高/列宽时使用
- `start_index` (int64, 可选): 起始索引(0-based),批量设置行高/列宽时使用
- `end_index` (int64, 可选): 结束索引(0-based),批量设置行高/列宽时使用
- `size` (number, 可选): 行高或列宽的值(行高单位为pt,列宽单位为像素),`is_clear` 为 `true` 时该字段将被忽略
- `is_clear` (bool, 可选): 是否清除自定义行高/列宽并恢复默认值,为 `true` 时 `size` 字段将被忽略
> 💡 **说明**:`index` 与 `start_index`/`end_index` 二选一。传 `index` 时设置单行/列;传 `start_index` + `end_index` 时批量设置该范围内所有行/列。
### 返回值说明
```json
{}
```
---
## 21. sheet.add_sheet
### 功能说明
在在线表格中添加一个新的子表,支持指定子表名称和位置(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"name": "新子表",
"index": 0,
"append_index": false
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `name` (string, 可选): 子表名称,长度限制为 31 个字符,不传则使用默认名称
- `index` (int64, 可选): 子表位置索引(0-based),不传或 `append_index` 为 `true` 时追加到末尾
- `append_index` (bool, 可选): 是否追加到末尾,为 `true` 时 `index` 字段将被忽略
> 注意:此工具不需要 `sheet_id` 参数,用于创建新的子表。
### 返回值说明
```json
{
"sheet_id": "new_sheet_001"
}
```
- `sheet_id` (string): 新创建的子表 ID
---
## 22. sheet.delete_sheet
### 功能说明
删除在线表格中指定的子表(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 要删除的子表 ID
### 返回值说明
```json
{}
```
---
## 23. sheet.rename_sheet
### 功能说明
重命名在线表格中指定的子表(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"name": "新名称"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `name` (string, 必填): 新的子表名称,长度限制为 31 个字符
### 返回值说明
```json
{}
```
---
## 24. sheet.insert_image
### 功能说明
在在线表格指定单元格插入一张图片,图片内容可通过 base64 或 image_id 传入(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"row_index": 0,
"col_index": 0,
"content": "iVBORw0KGgoAAAANSUhEUgAA..."
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `row_index` (int64, 必填): 目标行索引(0-based)
- `col_index` (int64, 必填): 目标列索引(0-based)
- `content` (string, 可选): 图片的 base64 内容,与 `image_id` 二选一,适合图片体积较小的场景;若图片过大导致 base64 内容超出传输限制,请改用 `image_id` 方式
- `image_id` (string, 可选): 图片的 image_id,本质是对图片信息加密后的字符串,与 `content` 二选一,适合图片体积较大的场景。获取方式:
- 通过 `upload_image` MCP 接口上传图片后获取
- 通过[腾讯文档开放平台 OpenAPI](https://docs.qq.com/open/developers/?nlc=1#/login) 图片上传接口获取:引导用户自行登录开放平台后台,完成 OAuth 授权并调用图片上传接口(`POST https://docs.qq.com/openapi/resources/v2/images`,multipart/form-data 直传图片文件)。`Access-Token`、`Client-Id`、`Open-Id` 等凭证由用户本人持有,不要代用户索取或经手。用户上传成功后,请其提供返回结果中的 `imageID` 字段值传入此参数
上传成功后,取返回结果中的 `imageID` 字段值传入此参数
### 返回值说明
```json
{}
```
---
## 25. sheet.set_range_value_by_csv
### 功能说明
以 CSV 格式批量插入数据到在线表格(SHEET),指定左上角起始行列和 CSV 内容,自动解析并写入对应单元格。相比 `set_range_value` 需要逐个指定每个单元格的行列和类型,`set_range_value_by_csv` 只需提供一段 CSV 文本即可,更适合批量写入表格数据的场景。
> 💡 **建议**:单次写入请求体内容尽量不超过 **1MB**,超大批量请拆分为多次写入。
> 💡 **类型自动检测**:CSV 中的每个字段会自动检测类型——数字识别为 `NUMBER`,`true`/`false` 识别为 `BOOL`,以 `=` 开头识别为 `FORMULA`,其余为 `STRING`。空字段会被跳过。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"csv_data": "Name,Score,Pass\nAlice,95.5,true\nBob,82,true\nCharlie,59,false"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` (int64, 可选): 左上角起始行索引(0-based),默认为 0
- `start_col` (int64, 可选): 左上角起始列索引(0-based),默认为 0
- `csv_data` (string, 必填): CSV 格式的数据内容,每行以换行符分隔,每列以逗号分隔,支持标准 CSV 引号转义
### 返回值说明
```json
{}
```
---
## 26. sheet.get_sheet_object_list
### 功能说明
获取在线表格指定子表上的对象列表,包括图表(chart)、透视表(pivot_table)、筛选表(table)、浮动图片(float_image)(SHEET)。支持按对象类型、显示区域、名称模糊匹配过滤。返回每个对象的 ID、类型、名称、显示区域、数据来源区域以及类型相关的简要信息。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"object_types": ["chart", "float_image"],
"filter_by_range": true,
"start_row": 0,
"start_col": 0,
"end_row": 50,
"end_col": 10,
"name_pattern": ""
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `object_types` (array, 可选): 对象类型过滤列表,留空表示返回所有类型;元素取值为字符串:`"chart"`(图表)、`"pivot_table"`(透视表)、`"table"`(筛选表)、`"float_image"`(浮动图片)
- `filter_by_range` (bool, 可选): 是否按区域过滤对象,为 `true` 时才根据 `start_row`/`start_col`/`end_row`/`end_col` 过滤
- `start_row` (int64, 可选): 显示区域过滤起始行索引(0-based),需要 `filter_by_range` 为 `true` 时才生效
- `start_col` (int64, 可选): 显示区域过滤起始列索引(0-based)
- `end_row` (int64, 可选): 显示区域过滤结束行索引
- `end_col` (int64, 可选): 显示区域过滤结束列索引
- `name_pattern` (string, 可选): 对象名称模糊匹配模式,留空表示不按名称过滤
### 返回值说明
```json
{
"objects": [
{
"object_id": "chart_001",
"object_type": "chart",
"name": "销售趋势图",
"display_range": "sub_sheet_001$A1:F15",
"data_range": "sub_sheet_001$A1:B10",
"chart_type": 1
}
]
}
```
- `objects` (array): 子表上的对象列表
- `object_id` (string): 对象唯一 ID
- `object_type` (string): 对象类型:`"chart"` / `"pivot_table"` / `"table"` / `"float_image"` / `"unknown"`
- `name` (string): 对象名称
- `display_range` (string): 显示区域,格式如 `"SheetID$A1:B2"`
- `data_range` (string): 数据来源区域,格式如 `"SheetID$A1:B2"`
- `chart_type` (int32): 图表类型枚举值,仅当 `object_type=="chart"` 时有效
- `pivot_row_group_count` (int32): 透视表行分组数
- `pivot_column_group_count` (int32): 透视表列分组数
- `pivot_value_count` (int32): 透视表值字段数
- `table_has_header` (bool): 筛选表是否含表头
- `table_column_count` (int32): 筛选表列数
- `float_image_width` (int32): 浮动图片宽度
- `float_image_height` (int32): 浮动图片高度
---
## 27. sheet.move_dimension
### 功能说明
在在线表格中移动一段连续的行或列到新的位置(SHEET)。移动语义与 Apps Script `moveRows`/`moveColumns` 一致:`index` 表示要移动的起始行/列索引(0-based),`count` 表示要移动的行/列数量,`to` 表示移动到的目标位置索引(0-based,相对原表)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"dimension_type": "row",
"index": 0,
"count": 3,
"to": 10
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `dimension_type` (string, 必填): 行列类型:`"row"` | `"col"`
- `index` (int64, 必填): 待移动的起始索引(0-based)
- `count` (int64, 必填): 待移动的行/列数量
- `to` (int64, 必填): 目标位置索引(0-based,相对原表)
### 返回值说明
```json
{}
```
---
## 28. sheet.update_filter
### 功能说明
更新在线表格已有筛选的范围和/或列筛选项(SHEET)。当前列筛选项**仅支持值筛选**(`FILTER_CRITERIA_VALUE`)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"is_update_range": true,
"start_row": 0,
"start_col": 0,
"end_row": 100,
"end_col": 5,
"columns": [
{ "col": 0, "visible_values": ["北京", "上海"] }
]
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `is_update_range` (bool, 可选): 是否更新筛选范围。`true` 时使用下面 4 个字段作为新筛选范围(4 字段必填);`false`(默认)保留原范围
- `start_row` / `start_col` / `end_row` / `end_col` (int64, 条件必填): 新的数据区域,仅当 `is_update_range=true` 时生效
- `columns` (array, 可选): 列筛选项列表,为空时不修改原列筛选项;每项:
- `col` (int64, 必填): 列索引(0-based,相对整个子表)
- `visible_values` (string[], 必填): 该列保留可见的值;不在列表内的值会被隐藏;传空列表代表隐藏该列全部值
### 返回值说明
```json
{}
```
---
## 29. sheet.find
### 功能说明
在表格中搜索指定文本,返回匹配的单元格位置(SHEET)。支持大小写敏感、整单元格匹配、正则表达式、搜索公式等选项;支持基于 `offset` / `max_results` 的分页。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"search_term": "张三",
"sheet_name": "Sheet1",
"match_case": false,
"match_entire_cell": false,
"use_regex": false,
"match_formulas": false,
"offset": 0,
"max_results": 50
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `search_term` (string, 必填): 要搜索的文本
- `sheet_name` (string, 可选): 限定搜索的子表名称,不指定则全表搜索
- `start_row` / `start_col` (int64, 可选): 搜索起始行/列(0-based,不传从 0 开始)
- `end_row` / `end_col` (int64, 可选): 搜索结束行/列(0-based,不传到最后一行/列)
- `offset` (int64, 可选): 分页偏移量(默认 0)
- `match_case` (bool, 可选): 大小写敏感(默认 `false`)
- `match_entire_cell` (bool, 可选): 整单元格匹配(默认 `false`)
- `use_regex` (bool, 可选): 将搜索文本作为正则表达式(默认 `false`)
- `match_formulas` (bool, 可选): 搜索公式内容(默认 `false`)
- `max_results` (int64, 可选): 每页最大结果数(默认 50)
> 注意:此工具不需要 `sheet_id` 参数,可通过 `sheet_name` 限定子表,未指定则全表搜索。
### 返回值说明
```json
{
"total_results": 12,
"results": [
{ "sheet_id": "sub_sheet_001", "row": 2, "col": 0, "address": "A3" }
],
"overflow": false,
"next_offset": 0
}
```
- `total_results` (int64): 本次查找命中的总结果数
- `results` (array): 当前页命中单元格列表,每项含 `sheet_id`、`row`/`col`(0-based)、`address`(A1 风格 1-based 地址)
- `overflow` (bool): 是否超过引擎底层 / 分页限制仍有更多未返回的结果
- `next_offset` (int64): 当 `overflow=true` 且仅因分页截断时下一页的 offset;后端原生 overflow 场景下为 0
---
## 30. sheet.get_cell_style
### 功能说明
获取在线表格指定区域单元格的样式信息(SHEET),包括背景色、字体颜色、字号、字体、数字格式。返回每个单元格的位置和样式字段,未设置的样式对应字段为空。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 5,
"end_col": 5
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` / `start_col` / `end_row` / `end_col` (int64, 必填): 查询区域(0-based)
### 返回值说明
```json
{
"cells": [
{
"row": 0,
"col": 0,
"background_color": "FFFFFF00",
"font_color": "FF000000",
"font_size": 12,
"font_family": "微软雅黑",
"number_format": ""
}
]
}
```
- `cells` (array): 单元格样式列表,区域内每个单元格一项
- `row` / `col` (int32): 行/列索引(0-based)
- `background_color` (string): 背景色 ARGB hex,未设置时为空
- `font_color` (string): 字体颜色 ARGB hex,未设置时为空
- `font_size` (int32): 字号 pt,未设置时为 0
- `font_family` (string): 字体名称,未设置时为空
- `number_format` (string): 数字格式,未设置时为空
---
## 31. sheet.move_sheet
### 功能说明
移动在线表格中子表的顺序,按源位置和目标位置(均为 0-based 索引)调整子表排列(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"src_index": 2,
"dest_index": 0
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `src_index` (int64, 必填): 源位置子表索引(0-based)
- `dest_index` (int64, 必填): 目标位置子表索引(0-based)
> 注意:此工具不需要 `sheet_id` 参数,按子表索引位置定位。
### 返回值说明
```json
{}
```
---
## 32. sheet.set_border
### 功能说明
设置在线表格指定区域单元格的边框样式(SHEET),支持设置上下左右及内部横竖边框,可指定边框颜色和线型。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 5,
"end_col": 5,
"border_positions": [0, 1, 2, 3],
"border_style": 1,
"border_color": "FF0000"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` / `start_col` / `end_row` / `end_col` (int64, 必填): 区域索引(0-based)
- `border_positions` (int[], 必填): 要设置的边框位置列表,至少一个;取值:
- `0` = 上边框(TOP)
- `1` = 下边框(BOTTOM)
- `2` = 左边框(LEFT)
- `3` = 右边框(RIGHT)
- `4` = 内部竖线(INNER_VERTICAL)
- `5` = 内部横线(INNER_HORIZONTAL)
- `border_style` (int, 可选): 边框线型,默认 `1`(细线);取值:
- `0` = 无、`1` = 细线、`2` = 中等、`3` = 虚线、`4` = 点线、`5` = 粗线、`6` = 双线、`7` = 极细线
- `border_color` (string, 可选): 边框颜色,RGB hex(不含 `#`),如 `"FF0000"`;不传则使用默认黑色
### 返回值说明
```json
{}
```
---
## 33. sheet.clear_border
### 功能说明
清除在线表格指定区域单元格的边框(SHEET),支持按位置清除指定边框或清除全部边框。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 5,
"end_col": 5,
"border_positions": [0, 1]
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` / `start_col` / `end_row` / `end_col` (int64, 必填): 区域索引(0-based)
- `border_positions` (int[], 可选): 要清除的边框位置列表(取值同 `set_border.border_positions`);不传则清除全部边框
### 返回值说明
```json
{}
```
---
## 34. sheet.sort_range
### 功能说明
对在线表格指定区域按列排序(SHEET),支持多列排序、表头识别和筛选区域内排序(仅支持单列)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 100,
"end_col": 5,
"has_header": true,
"columns": [
{ "col": 2, "order": 1 },
{ "col": 0, "order": 0 }
]
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` / `start_col` / `end_row` / `end_col` (int64, 必填): 排序区域(0-based)
- `has_header` (bool, 可选): 是否含表头(首行不参与排序,默认 `false`)
- `columns` (array, 必填): 排序列列表,至少一个,多列时按顺序依次作为排序键。每项:
- `col` (int64, 必填): 列索引(0-based,相对于整个子表)
- `order` (int, 可选): 排序方向:`0` = 降序(默认)、`1` = 升序
- `table_id` (string, 可选): 筛选表 ID。传入时表示在筛选区域内排序,**仅支持单列排序**
### 返回值说明
```json
{}
```
---
## 35. sheet.add_chart
### 功能说明
在在线表格中添加图表(SHEET),支持指定图表类型、数据范围、位置大小等参数,自动从数据范围构建图表配置。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"chart_type": "CHART_CLUSTERED_COLUMN",
"data_range": {
"start_row": 0,
"start_col": 0,
"end_row": 9,
"end_col": 1
},
"location": {
"row_index": 1,
"col_index": 4
},
"drawing_id": "chart_001",
"title": "销售趋势"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `chart_type` (string, 必填): 图表类型枚举名,常用取值:
- 面积图:`CHART_AREA` / `CHART_AREA_3D` / `CHART_STACKED_AREA` / `CHART_PERCENT_STACKED_AREA`
- 折线图:`CHART_LINE` / `CHART_LINE_3D` / `CHART_STACKED_LINE`
- 股价图:`CHART_HIGH_LOW_CLOSE_STOCK`
- 雷达图:`CHART_RADAR`
- 散点图:`CHART_SCATTER`
- 饼图:`CHART_PIE`
- 条形图:`CHART_CLUSTERED_BAR`
- 柱形图:`CHART_CLUSTERED_COLUMN`
- 气泡图:`CHART_BUBBLE`
- 组合图:`CHART_CUSTOM_COMBO`
- 其他:`CHART_REGION_MAP` / `CHART_TREEMAP`
- `data_range` (object, 必填): 数据范围
- `start_row` / `start_col` / `end_row` / `end_col` (int32, 必填): 数据区域(0-based)
- `drawing_id` (string, 必填): 图表标识ID,由调用方生成(用于后续删除/更新图表)
- `location` (object, 可选): 图表位置和大小,不传则使用默认位置
- `row_index` (int32): 锚定单元格行索引(0-based)
- `col_index` (int32): 锚定单元格列索引(0-based)
- `horizontal_offset` (int32, 可选): 单元格内水平偏移
- `vertical_offset` (int32, 可选): 单元格内垂直偏移
- `width` (int32, 可选): 图表宽度
- `height` (int32, 可选): 图表高度
- `use_column_as_series` (bool, 可选): 列作为系列(不设则自动检测)
- `first_row_as_header` (bool, 可选): 首行作为表头/系列名(不设则自动检测)
- `first_column_as_category` (bool, 可选): 首列作为分类轴(不设则自动检测)
- `title` (string, 可选): 图表显示标题
### 返回值说明
```json
{}
```
---
## 36. sheet.delete_chart
### 功能说明
删除在线表格中指定的图表(SHEET)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"drawing_id": "chart_001"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `drawing_id` (string, 必填): 要删除的图表标识ID
### 返回值说明
```json
{}
```
---
## 37. sheet.get_charts
### 功能说明
获取在线表格指定子表下的所有图表信息(SHEET),包括图表 ID、类型、标题、位置、数据范围以及完整 ChartOptions JSON。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
### 返回值说明
```json
{
"charts": [
{
"drawing_id": "chart_001",
"chart_type": "CHART_CLUSTERED_COLUMN",
"title": "销售趋势",
"location": { "row_index": 1, "col_index": 4 },
"data_range": { "start_row": 0, "start_col": 0, "end_row": 9, "end_col": 1 },
"options_json": "{\"title\":...,\"series\":...}"
}
]
}
```
- `charts` (array): 图表信息列表
- `drawing_id` (string): 图表标识ID
- `chart_type` (string): 图表类型枚举名
- `title` (string): 图表标题
- `location` (object): 图表位置和大小(与 `add_chart.location` 同结构)
- `data_range` (object): 图表数据范围(与 `add_chart.data_range` 同结构)
- `options_json` (string): 图表完整 options 配置(JSON 字符串),客户端按需 `JSON.parse`;顶层 key 包含 `title` / `legend` / `xAxis` / `yAxis` / `secondaryYAxis` / `series` 等
---
## 38. sheet.update_chart
### 功能说明
更新在线表格中指定图表的类型、数据范围、位置尺寸、标题等配置(SHEET),未传字段保持原值。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"drawing_id": "chart_001",
"chart_type": "CHART_LINE",
"title": "新标题",
"bool_options": {
"use_column_as_series": { "value": true }
}
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `drawing_id` (string, 必填): 图表标识ID
- `chart_type` (string, 可选): 图表类型枚举名(取值同 `add_chart.chart_type`),不传保持原类型
- `location` (object, 可选): 位置和尺寸,结构同 `add_chart.location`
- `data_range` (object, 可选): 数据源区域,结构同 `add_chart.data_range`
- `bool_options` (object, 可选): 布尔选项,使用 `BoolValue` 包装类型区分"未传"和"传了 false"
- `use_column_as_series` (BoolValue): 列作为系列
- `first_row_as_header` (BoolValue): 首行作为表头
- `first_column_as_category` (BoolValue): 首列作为分类轴
- `title` (string, 可选): 图表标题
- `options_json` (string, 可选): 完整 ChartOptions JSON(高级配置)
### 返回值说明
```json
{}
```
---
## 39. sheet.insert_range
### 功能说明
在指定区域插入空白单元格(SHEET)。`dimension_type=col` 时按列插入(选中区域及其右侧单元格右移);`dimension_type=row` 时按行插入(选中区域及其下方单元格下移)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 2,
"end_col": 2,
"dimension_type": "row"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` / `start_col` / `end_row` / `end_col` (int64, 必填): 区域索引(0-based)
- `dimension_type` (string, 必填): 移动方式:`"col"`(右移)| `"row"`(下移)
### 返回值说明
```json
{}
```
---
## 40. sheet.delete_range
### 功能说明
在指定区域删除单元格(SHEET)。`dimension_type=col` 时按列删除(右侧单元格左移);`dimension_type=row` 时按行删除(下方单元格上移)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"start_row": 0,
"start_col": 0,
"end_row": 2,
"end_col": 2,
"dimension_type": "row"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 子表 ID
- `start_row` / `start_col` / `end_row` / `end_col` (int64, 必填): 区域索引(0-based)
- `dimension_type` (string, 必填): 移动方式:`"col"`(左移)| `"row"`(上移)
### 返回值说明
```json
{}
```
---
## 41. sheet.validate_file_data
### 功能说明
校验在线表格指定版本的数据是否正常(**排障专用**,SHEET)。内部走 `GetKeyframe` 并开启 `enable_mutation_check`,若任意一条 mutation 在回放前的校验阶段失败,则返回 `is_valid=false` 以及失败 mutation 的阶段、类型、详细原因。推荐 `is_latest=true` 直接校验最新版本。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"is_latest": true
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `version` (int64, 可选): 要校验的修订版本号;当 `is_latest=true` 时该字段被忽略
- `is_latest` (bool, 可选): 是否校验最新版本。`true` 时忽略 `version`,服务端用 meta 的最新版本号;`false` 时使用 `version` 指定历史版本
> 注意:此工具不需要 `sheet_id` 参数,校验整个文档数据。
### 返回值说明
```json
{
"is_valid": false,
"checked_version": 12345,
"ret_code": 0,
"stage": "RebuildSheet",
"failed_mutation_type": 27,
"err_msg": "stage=RebuildSheet, type=27, detail=..."
}
```
- `is_valid` (bool): 是否通过校验:`true`=数据正常;`false`=存在非法 mutation
- `checked_version` (int64): 本次实际校验的版本号
- `ret_code` (int32): C++ 侧返回的错误码;校验通过时为 0;失败时为 GetKeyframe 底层错误码
- `stage` (string): 首个校验失败所在回放阶段,可能取值:`RebuildWorkbook.workbook_cmds` / `RebuildWorkbook.revisions` / `RebuildSheet` / `RebuildSheetWithTrim` / `ApplyNewRevisions`;校验通过时为空
- `failed_mutation_type` (int32): 首个校验失败的 mutation 类型枚举整数值;校验通过时为 0
- `err_msg` (string): 完整错误信息(含 stage / type / detail 上下文);校验通过时为空
---
## 42. sheet.add_pivot_table
### 功能说明
在在线表格中创建透视表(SHEET)。`anchor` 指定透视表放置位置(左上角单元格),`source_range` 指定数据源区域,`pivot_table_id` 由调用方生成并保持唯一。`create_new_sheet=true` 时由引擎新建子表放置(忽略 `anchor_sheet_id`);`create_new_sheet=false`(默认)时 `anchor_sheet_id` 必填,`anchor_row`/`anchor_col` 默认为 0。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"pivot_table_id": "pt_001",
"name": "销售透视",
"source_sheet_id": "sub_sheet_001",
"source_range": {
"start_row": 0,
"start_col": 0,
"end_row": 100,
"end_col": 5
},
"anchor_sheet_id": "sub_sheet_002",
"anchor_row": 0,
"anchor_col": 0,
"create_new_sheet": false
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `pivot_table_id` (string, 必填): 透视表唯一ID(由调用方生成并保持唯一)
- `name` (string, 可选): 透视表显示名称
- `source_sheet_id` (string, 必填): 数据源所在子表ID
- `source_range` (object, 必填): 数据源区域,4 个字段均必填
- `start_row` / `start_col` / `end_row` / `end_col` (int64, 必填): 数据源区域(0-based)
- `anchor_sheet_id` (string, 条件必填): 锚点(透视表左上角)所在子表ID,`create_new_sheet=false` 时必填,`true` 时忽略
- `anchor_row` (int64, 可选): 锚点行索引(0-based,默认 0)
- `anchor_col` (int64, 可选): 锚点列索引(0-based,默认 0)
- `create_new_sheet` (bool, 可选): 是否新建子表放置透视表,默认 `false`
- `new_sheet_id` (string, 可选): 新建子表的 ID(`create_new_sheet=true` 时使用)
> 注意:此工具不需要顶层 `sheet_id` 参数,使用 `source_sheet_id` 与 `anchor_sheet_id` 分别指定数据源和锚点子表。
### 返回值说明
```json
{}
```
---
## 43. sheet.remove_pivot_table
### 功能说明
删除在线表格中已存在的透视表(SHEET)。通过 `sheet_id` 与 `pivot_table_id` 联合定位目标透视表,删除后其关联的 pivot cache 会被一并清理。`sheet_id` 必须是 worksheet 子表。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_002",
"pivot_table_id": "pt_001"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 目标透视表所在子表ID(必须是 worksheet)
- `pivot_table_id` (string, 必填): 目标透视表ID
### 返回值说明
```json
{}
```
---
## 44. sheet.get_pivot_table_detail
### 功能说明
读取指定透视表的详细配置(数据源、行/列/值/筛选、锚点位置、ID 等),用于展示或回显,不会修改文档(SHEET)。`pivot_table_id` 与 `pivot_table_name` 至少传一个,**id 优先**。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"pivot_table_id": "pt_001"
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `pivot_table_id` (string, 二选一): 目标透视表ID(与 `pivot_table_name` 二选一,id 优先)
- `pivot_table_name` (string, 二选一): 目标透视表显示名称
> 注意:此工具不需要 `sheet_id` 参数。
### 返回值说明
```json
{
"pivot_table": {
"pivot_table_id": "pt_001",
"pivot_table_name": "销售透视",
"anchor_sheet_id": "sub_sheet_002",
"anchor_row": 0,
"anchor_col": 0,
"row_group_columns": [0],
"column_group_columns": [1],
"source_sheet_id": "sub_sheet_001",
"source_data_range": {
"sheet_id": "sub_sheet_001",
"start_row_index": 0,
"start_col_index": 0,
"end_row_index": 100,
"end_col_index": 5
},
"pivot_values": [
{ "source_data_column": 2, "summarize_function": "SUM" }
],
"filters": [
{ "source_data_column": 3, "visible_values": ["北京"] }
]
}
}
```
- `pivot_table` (object): 透视表详情
- `pivot_table_id` (string): 透视表ID
- `pivot_table_name` (string): 透视表显示名称
- `anchor_sheet_id` (string): 锚点所在子表ID
- `anchor_row` / `anchor_col` (int32): 锚点行/列索引(0-based)
- `row_group_columns` (int32[]): 行分组的源数据列索引列表
- `column_group_columns` (int32[]): 列分组的源数据列索引列表
- `source_sheet_id` (string): 数据源所在子表ID
- `source_data_range` (object): 数据源范围(GridRange,含 `sheet_id` / `start_row_index` / `start_col_index` / `end_row_index` / `end_col_index`)
- `pivot_values` (array): 数据值字段列表
- `source_data_column` (int32): 源数据列索引(0-based)
- `summarize_function` (string): 聚合函数大写名(`SUM` / `COUNT` / `AVERAGE` / `MAX` / `MIN` / `PRODUCT` / `COUNTNUMS` / `STDEV` / `STDEVP` / `VAR` / `VARP`)
- `filters` (array): 页字段筛选器列表
- `source_data_column` (int32): 源数据列索引(0-based)
- `visible_values` (string[]): 保留可见的值
---
## 45. sheet.update_pivot_table
### 功能说明
更新已有透视表的字段配置(行分组、列分组、数据值、筛选、计算字段,SHEET)。**替换语义**:每次调用整体替换字段配置,未传入的分类视为清空;推荐先调 `get_pivot_table_detail` 拉取当前配置后再下发。`sheet_id` 必须是 worksheet。
> ⚠️ **校验规则**:
> - `pivot_values[].summarize_function` 必填且不区分大小写,合法值:`SUM` / `COUNT` / `COUNTA` / `AVERAGE` / `MAX` / `MIN` / `PRODUCT` / `COUNTNUMS` / `STDEV` / `STDEVP` / `VAR` / `VARP`(COUNTA 等同于 COUNT)
> - `calculated_values[]` 中 `name` 与 `formula` 均不能为空
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_002",
"pivot_table_id": "pt_001",
"row_groups": [{ "source_data_column": 0 }],
"column_groups": [{ "source_data_column": 1 }],
"pivot_values": [
{ "source_data_column": 2, "summarize_function": "SUM" }
],
"filters": [
{ "source_data_column": 3, "visible_values": ["北京", "上海"] }
],
"calculated_values": [
{ "name": "毛利率", "formula": "=利润/收入" }
]
}
```
### 参数说明
- `file_id` (string, 必填): 文档 ID
- `sheet_id` (string, 必填): 透视表所在子表ID(必须是 worksheet)
- `pivot_table_id` (string, 必填): 目标透视表ID
- `row_groups` (array, 可选): 行分组字段(替换语义),每项 `{ source_data_column: int }`
- `column_groups` (array, 可选): 列分组字段(替换语义),每项 `{ source_data_column: int }`
- `pivot_values` (array, 可选): 数据值字段(替换语义),每项:
- `source_data_column` (int32, 必填): 源数据列索引(0-based)
- `summarize_function` (string, 必填): 聚合函数名称,不区分大小写,合法值见上方校验规则
- `filters` (array, 可选): 页字段筛选器(替换语义),每项:
- `source_data_column` (int32, 必填): 源数据列索引(0-based)
- `visible_values` (string[], 可选): 保留可见的值列表
- `calculated_values` (array, 可选): 计算字段(替换语义),每项:
- `name` (string, 必填): 字段名
- `formula` (string, 必填): 计算公式
### 返回值说明
```json
{}
```
---
## 46. sheet.add_protect_range
### 功能说明
在在线表格指定普通子表(worksheet)的单个矩形区域或整张子表创建保护区域(SHEET)。创建成功会同步在区域权限服务创建默认权限记录,并返回后续更新或删除使用的 `protect_range_id`。
### 调用示例
#### 示例 1:保护指定区域
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"range": {
"start_row": 0,
"start_col": 0,
"end_row": 10,
"end_col": 5
}
}
```
#### 示例 2:保护整张子表
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001",
"whole_sheet": true
}
```
### 参数说明
- `file_id` (string, 可选): 文档 ID,与 `file_url` 二选一
- `file_url` (string, 可选): 在线表格的 URL 链接,与 `file_id` 二选一
- `sheet_id` (string, 必填): 子表 ID(仅支持普通子表 worksheet)
- `range` (object, 可选): 保护区域范围,单个矩形区域;与 `whole_sheet` 二选一。未传或传 `false` 的 `whole_sheet` 时,必须传 `range`
- `start_row` (int64, 必填): 起始行索引(0-based)
- `start_col` (int64, 必填): 起始列索引(0-based)
- `end_row` (int64, 必填): 结束行索引(0-based,不包含该行)
- `end_col` (int64, 必填): 结束列索引(0-based,不包含该列)
- `whole_sheet` (bool, 可选): 是否保护整张子表;传 `true` 时不能同时传 `range`
### 返回值说明
```json
{
"protect_range_id": "protected_range_001"
}
```
---
## 47. sheet.update_protect_range
### 功能说明
按 `protect_range_id` 修改在线表格已有保护区域的范围(SHEET)。`range` 为替换后的单个矩形区域,仅支持普通子表(worksheet)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"protect_range_id": "protected_range_001",
"range": {
"start_row": 2,
"start_col": 1,
"end_row": 12,
"end_col": 6
}
}
```
### 参数说明
- `file_id` (string, 可选): 文档 ID,与 `file_url` 二选一
- `file_url` (string, 可选): 在线表格的 URL 链接,与 `file_id` 二选一
- `sheet_id` (string, 可选): 子表 ID;`protect_range_id` 可唯一定位子表,传入时需与保护区域所在子表一致
- `protect_range_id` (string, 必填): 要修改的保护区域 ID,由 `sheet.add_protect_range` 返回
- `range` (object, 必填): 新保护区域范围,替换语义,单个矩形区域
- `start_row` (int64, 必填): 起始行索引(0-based)
- `start_col` (int64, 必填): 起始列索引(0-based)
- `end_row` (int64, 必填): 结束行索引(0-based,不包含该行)
- `end_col` (int64, 必填): 结束列索引(0-based,不包含该列)
### 返回值说明
```json
{}
```
---
## 48. sheet.delete_protect_range
### 功能说明
按 `protect_range_id` 删除在线表格已有保护区域(SHEET),并同步清理区域权限服务记录。仅支持普通子表(worksheet)。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"protect_range_id": "protected_range_001"
}
```
### 参数说明
- `file_id` (string, 可选): 文档 ID,与 `file_url` 二选一
- `file_url` (string, 可选): 在线表格的 URL 链接,与 `file_id` 二选一
- `sheet_id` (string, 可选): 子表 ID;`protect_range_id` 可唯一定位子表,传入时需与保护区域所在子表一致
- `protect_range_id` (string, 必填): 要删除的保护区域 ID
### 返回值说明
```json
{}
```
---
## 49. sheet.get_protect_ranges
### 功能说明
获取在线表格指定普通子表(worksheet)的所有保护区域(SHEET),返回每个保护区域的 `protect_range_id` 与 `range`。整张子表保护区域也会以 `range` 形式返回。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"sheet_id": "sub_sheet_001"
}
```
### 参数说明
- `file_id` (string, 可选): 文档 ID,与 `file_url` 二选一
- `file_url` (string, 可选): 在线表格的 URL 链接,与 `file_id` 二选一
- `sheet_id` (string, 必填): 子表 ID(仅支持普通子表 worksheet)
### 返回值说明
```json
{
"ranges": [
{
"protect_range_id": "protected_range_001",
"range": {
"start_row": 0,
"start_col": 0,
"end_row": 10,
"end_col": 5
}
}
]
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |