stock-assistant/skills/tencent-docs/references/smartsheet_references.md

智能表格（SmartSheet）工具完整参考文档

腾讯文档智能表格（SmartSheet）提供了一套完整的表格操作 API，支持对工作表、视图、字段、记录进行增删改查操作。

---

目录

• 概念说明
• 工作表（SubSheet）操作
  • smartsheet.list_tables - 列出工作表
  • smartsheet.add_table - 新增工作表
  • smartsheet.delete_table - 删除工作表
• 视图（View）操作
  • smartsheet.list_views - 列出视图
  • smartsheet.add_view - 新增视图
  • smartsheet.delete_view - 删除视图
• 字段（Field）操作
  • smartsheet.list_fields - 列出字段
  • smartsheet.add_fields - 新增字段
  • smartsheet.update_fields - 更新字段
  • smartsheet.delete_fields - 删除字段
• 记录（Record）操作
  • smartsheet.list_records - 列出记录
  • smartsheet.add_records - 新增记录
  • smartsheet.update_records - 更新记录
  • smartsheet.delete_records - 删除记录
• 枚举值参考
• 字段值格式参考
• 典型工作流示例

---

概念说明

概念	说明
file_id	智能表格文档的唯一标识符，每个文档有唯一的 file_id
sheet_id	工作表 ID，一个智能表格文档可包含多个工作表
view_id	视图 ID，每个工作表可有多个视图（网格视图、看板视图等）
field_id	字段 ID，对应表格的列
record_id	记录 ID，对应表格的行

层级关系：file_id（文档） → sheet_id（工作表） → view_id（视图） / field_id（字段） / record_id（记录）

---

工作表（SubSheet）操作

smartsheet.list_tables

功能：列出文档下的所有工作表，返回工作表基本信息列表。

使用场景：

• 查看一个智能表格文档中有哪些工作表
• 获取 sheet_id 以便后续操作字段、记录、视图

请求参数：

参数	类型	必填	说明
file_id	string	✅	智能表格文档的唯一标识符

返回字段：

字段	类型	说明
sheets	array	工作表列表
sheets[].sheet_id	string	工作表唯一标识符
sheets[].title	string	工作表名称
sheets[].is_visible	bool	工作表可见性
error	string	错误信息，操作失败时返回
trace_id	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id"
}

返回示例：

{
  "sheets": [
    {
      "sheet_id": "sheet_abc123",
      "title": "任务列表",
      "is_visible": true
    },
    {
      "sheet_id": "sheet_def456",
      "title": "已归档",
      "is_visible": false
    }
  ],
  "error": "",
  "trace_id": "trace_xyz"
}

---

smartsheet.add_table

功能：在文档中新增工作表，支持设置工作表名称和初始配置。

使用场景：

• 在已有智能表格文档中添加新的工作表（如新增"2024年Q2"工作表）
• 按业务模块拆分数据到不同工作表

请求参数：

参数	类型	必填	说明
file_id	string	✅	智能表格文档的唯一标识符
properties	object	✅	工作表属性配置
properties.sheet_id	string	✅	工作表名称（注意：此字段实际含义为工作表名称）
properties.title	string		工作表标题
properties.index	uint32		工作表下标（位置）

返回字段：

字段	类型	说明
properties	object	新创建工作表的属性信息
properties.sheet_id	string	工作表名称
properties.title	string	工作表标题
properties.index	uint32	工作表下标
error	string	错误信息
trace_id	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "properties": {
    "sheet_id": "新工作表",
    "title": "2024年Q2数据",
    "index": 1
  }
}

---

smartsheet.delete_table

功能：删除指定的工作表。

使用场景：

• 删除不再需要的工作表
• 清理测试数据工作表

请求参数：

参数	类型	必填	说明
file_id	string	✅	智能表格文档的唯一标识符
sheet_id	string	✅	要删除的工作表 ID

返回字段：

字段	类型	说明
error	string	错误信息，操作失败时返回
trace_id	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123"
}

---

视图（View）操作

smartsheet.list_views

功能：列出工作表下的所有视图，返回视图基本信息和配置。

使用场景：

• 查看工作表有哪些视图（网格视图、看板视图）
• 获取 view_id 以便按视图筛选记录或字段

请求参数：

参数	类型	必填	说明
file_id	string	✅	智能表格文档的唯一标识符
sheet_id	string	✅	工作表 ID
view_ids	[]string		需要查询的视图 ID 数组，不填则返回全部
offset	uint32		分页查询偏移量，默认 0
limit	uint32		分页大小，最大 100

返回字段：

字段	类型	说明
views	array	视图列表
views[].view_id	string	视图唯一标识符
views[].view_name	string	视图名称
views[].view_type	uint32	视图类型，枚举值见下方
total	uint32	符合条件的视图总数
hasMore	bool	是否还有更多项
next	uint32	下一页偏移量
error	string	错误信息
trace_id	string	调用链追踪 ID

视图类型枚举值：

值	说明
1	网格视图（grid）
2	看板视图（kanban）

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "offset": 0,
  "limit": 20
}

---

smartsheet.add_view

功能：在工作表中新增视图，支持自定义视图名称和类型。

使用场景：

• 为工作表创建看板视图，按状态分组展示任务
• 创建多个网格视图，分别展示不同筛选条件的数据

请求参数：

参数	类型	必填	说明
file_id	string	✅	智能表格文档的唯一标识符
sheet_id	string	✅	工作表 ID
view_title	string	✅	视图标题
view_type	uint32		视图类型：1-网格视图，2-看板视图

返回字段：

字段	类型	说明
view_id	string	新创建的视图 ID
view_title	string	视图标题
view_type	uint32	视图类型
error	string	错误信息
trace_id	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "view_title": "按状态分组",
  "view_type": 2
}

---

smartsheet.delete_view

功能：删除指定的视图，支持批量删除多个视图。

使用场景：

• 删除不再使用的视图
• 批量清理多余视图

请求参数：

参数	类型	必填	说明
file_id	string	✅	智能表格文档的唯一标识符
sheet_id	string	✅	工作表 ID
view_ids	[]string	✅	要删除的视图 ID 列表

返回字段：

字段	类型	说明
error	string	错误信息
trace_id	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "view_ids": ["view_id1", "view_id2"]
}

---

字段（Field）操作

smartsheet.list_fields

功能：列出工作表的所有字段，返回字段基本信息和类型配置。

使用场景：

• 查看工作表有哪些列（字段）及其类型
• 获取 field_id 以便后续更新或删除字段
• 在写入记录前，先了解字段结构和类型

请求参数：

参数	类型	必填	说明
file_id	string	✅	智能表格文档的唯一标识符
sheet_id	string	✅	工作表 ID
view_id	string		视图 ID，按视图筛选字段
field_ids	[]string		指定字段 ID 数组
field_titles	[]string		指定字段标题数组
offset	uint32		偏移量，初始值为 0
limit	uint32		分页大小，最大 100；不填或为 0 时，总数 >100 返回 100 条，否则返回全部

返回字段：

字段	类型	说明
total	uint32	符合条件的字段总数
has_more	bool	是否还有更多项
next	uint32	下一页偏移量
fields	array	字段列表，详见 FieldInfo 结构

FieldInfo 结构：

字段	类型	说明
field_id	string	字段唯一 ID
field_title	string	字段标题（列名）
field_type	uint32	字段类型，枚举值见下方
property_*	object	字段属性，根据 field_type 不同而不同

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123"
}

---

smartsheet.add_fields

功能：批量新增字段（列），支持同时添加多个不同类型的字段。

使用场景：

• 为工作表添加新列，如"优先级"（单选）、"截止日期"（日期）、"负责人"（用户）
• 初始化工作表结构

请求参数：

参数	类型	必填	说明
file_id	string	✅	智能表格文档的唯一标识符
sheet_id	string	✅	工作表 ID
fields	[]FieldInfo	✅	要添加的字段列表

FieldInfo 参数说明：

字段	类型	必填	说明
field_title	string	✅	字段标题（列名）
field_type	uint32	✅	字段类型，枚举值见下方
property_text	object		文本类型属性（无需额外配置）
property_number	object		数字类型属性
property_checkbox	object		复选框类型属性
property_date_time	object		日期时间类型属性
property_url	object		超链接类型属性
property_select	object		多选类型属性
property_single_select	object		单选类型属性
property_progress	object		进度类型属性

返回字段：

字段	类型	说明
fields	array	添加成功的字段列表（含 field_id）
error	string	错误信息
trace_id	string	调用链追踪 ID

调用示例（添加多种类型字段）：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "fields": [
      {
        "field_title": "任务名称",
        "field_type": 1,
        "property_text": {}
      },
      {
        "field_title": "优先级",
        "field_type": 17,
        "property_single_select": {
          "options": [
            { "text": "高", "style": 1 },
            { "text": "中", "style": 3 },
            { "text": "低", "style": 4 }
          ]
        }
      },
      {
        "field_title": "截止日期",
        "field_type": 4,
        "property_date_time": {
          "format": "yyyy-mm-dd",
          "auto_fill": false
        }
      },
      {
        "field_title": "完成进度",
        "field_type": 14,
        "property_progress": {
          "decimal_places": 0
        }
      },
      {
        "field_title": "是否完成",
        "field_type": 3,
        "property_checkbox": {
          "checked": false
        }
      }
    ]
}

---

smartsheet.update_fields

功能：批量更新字段属性，支持修改字段名称和配置信息。

使用场景：

• 修改字段标题（列名）
• 更新单选/多选字段的选项列表
• 修改数字字段的精度配置

⚠️ 注意：field_type（字段类型）不允许被更新，但更新时必须传入原字段类型值。

请求参数：

参数	类型	必填	说明
file_id	string	✅	智能表格文档的唯一标识符
sheet_id	string	✅	工作表 ID
fields	[]FieldInfo	✅	要更新的字段列表，必须包含 field_id

返回字段：

字段	类型	说明
fields	array	更新成功的字段列表
error	string	错误信息
trace_id	string	调用链追踪 ID

调用示例（修改字段标题和选项）：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "fields": [
      {
        "field_id": "field_id_001",
        "field_title": "任务状态",
        "field_type": 17,
        "property_single_select": {
          "options": [
            { "text": "待处理", "style": 7 },
            { "text": "进行中", "style": 3 },
            { "text": "已完成", "style": 4 },
            { "text": "已取消", "style": 1 }
          ]
        }
      }
    ]
}

---

smartsheet.delete_fields

功能：批量删除字段（列），支持同时删除多个字段。

使用场景：

• 删除不再需要的列
• 清理冗余字段

请求参数：

参数	类型	必填	说明
file_id	string	✅	智能表格文档的唯一标识符
sheet_id	string	✅	工作表 ID
field_ids	[]string	✅	要删除的字段 ID 数组

返回字段：

字段	类型	说明
error	string	错误信息
trace_id	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "field_ids": ["field_id_001", "field_id_002"]
}

---

记录（Record）操作

smartsheet.list_records

功能：分页列出工作表记录（行），支持排序和按字段筛选。

使用场景：

• 读取工作表中的数据
• 按特定字段排序查看数据
• 分页获取大量数据

请求参数：

参数	类型	必填	说明
file_id	string	✅	智能表格文档的唯一标识符
sheet_id	string	✅	工作表 ID
view_id	string		视图 ID，按视图筛选记录
record_ids	[]string		指定记录 ID 数组，精确查询
field_titles	[]string		只返回指定字段标题的值，不填则返回全部字段
sort	[]Sort		排序配置
offset	uint32		偏移量，初始值为 0
limit	uint32		分页大小，最大 100；不填或为 0 时，总数 >100 返回 100 条，否则返回全部

Sort 排序配置：

字段	类型	必填	说明
field_title	string	✅	需要排序的字段标题
desc	bool		是否降序，默认 false（升序）

返回字段：

字段	类型	说明
total	uint32	符合条件的记录总数
has_more	bool	是否还有更多项
next	uint32	下一页偏移量
records	array	记录列表，详见 RecordInfo 结构
error	string	错误信息
trace_id	string	调用链追踪 ID

RecordInfo 结构：

字段	类型	说明
record_id	string	记录唯一 ID
field_values	map	字段值映射，key 为字段标题，value 为字段值

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "field_titles": ["任务名称", "优先级", "截止日期"],
  "sort": [
    { "field_title": "截止日期", "desc": false }
  ],
  "offset": 0,
  "limit": 50
}

---

smartsheet.add_records

功能：批量添加记录（行），支持同时添加多条记录数据。

使用场景：

• 批量导入数据到工作表
• 添加新任务、新条目
• 从其他数据源同步数据

请求参数：

参数	类型	必填	说明
file_id	string	✅	智能表格文档的唯一标识符
sheet_id	string	✅	工作表 ID
records	[]AddRecord	✅	要添加的记录列表

AddRecord 结构：

字段	类型	必填	说明
field_values	map	✅	字段值映射，key 为字段标题，value 为字段值（格式见下方）

返回字段：

字段	类型	说明
records	array	添加成功的记录列表（含 record_id）
error	string	错误信息
trace_id	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "records": [
      {
        "field_values": {
          "任务名称": [{"text": "完成需求文档", "type": "text"}],
          "优先级": [{"text": "高"}],
          "截止日期": "1720000000000",
          "完成进度": 30,
          "是否完成": false
        }
      },
      {
        "field_values": {
          "任务名称": [{"text": "代码评审", "type": "text"}],
          "优先级": [{"text": "中"}],
          "截止日期": "1720086400000",
          "完成进度": 0,
          "是否完成": false
        }
      }
    ]
}

---

smartsheet.update_records

功能：批量更新记录，支持修改多条记录的字段值。

使用场景：

• 更新任务状态、进度
• 修改记录中的某些字段值
• 批量修改多条数据

请求参数：

参数	类型	必填	说明
file_id	string	✅	智能表格文档的唯一标识符
sheet_id	string	✅	工作表 ID
records	[]RecordInfo	✅	要更新的记录列表，必须包含 record_id

RecordInfo 参数说明：

字段	类型	必填	说明
record_id	string	✅	记录 ID，标识要更新哪条记录
field_values	map	✅	要更新的字段值映射

返回字段：

字段	类型	说明
error	string	错误信息
trace_id	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "records": [
      {
        "record_id": "record_id_001",
        "field_values": {
          "完成进度": 100,
          "是否完成": true,
          "优先级": [{"text": "高"}]
        }
      }
    ]
}

---

smartsheet.delete_records

功能：批量删除记录（行），支持同时删除多条指定的记录。

使用场景：

• 删除已完成或过期的任务记录
• 清理测试数据
• 批量删除多条记录

请求参数：

参数	类型	必填	说明
file_id	string	✅	智能表格文档的唯一标识符
sheet_id	string	✅	工作表 ID
record_ids	[]string	✅	要删除的记录 ID 列表

返回字段：

字段	类型	说明
error	string	错误信息
trace_id	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "sheet_id": "sheet_abc123",
  "record_ids": ["record_id_001", "record_id_002", "record_id_003"]
}

---

枚举值参考

字段类型（field_type）

枚举值	类型名称	对应 property 字段	说明
1	文本	property_text	普通文本，无需额外配置
2	数字	property_number	整数或浮点数
3	复选框	property_checkbox	布尔值 true/false
4	日期	property_date_time	毫秒时间戳字符串
5	图片	property_image	图片 ID 数组
8	超链接	property_url	URL 数组
9	多选	property_select	选项数组（可多选）
10	创建人	property_user	系统自动填充，无需配置
11	最后编辑人	property_modified_user	系统自动填充，无需配置
12	创建时间	property_created_time	系统自动填充，无需配置
13	最后编辑时间	property_modified_time	系统自动填充，无需配置
14	进度	property_progress	整数或浮点数（百分比）
15	电话	property_phone_number	字符串，无需额外配置
16	邮件	property_email	字符串，无需额外配置
17	单选	property_single_select	选项数组（只能单选）
18	关联	-	关联其他记录，值为 record_id 字符串数组
25	自动编号	-	系统自动生成编号，无需手动配置
26	货币	-	浮点数，表示货币金额
28	百分比	-	浮点数，如 0.75 表示 75%

视图类型（view_type）

枚举值	说明
1	网格视图（grid）- 传统表格形式
2	看板视图（kanban）- 按列分组展示

选项颜色（style）

枚举值	颜色
1	红色
2	橘黄色
3	蓝色
4	绿色
5	紫色
6	粉色
7	灰色
8	白色

超链接展示样式（UrlFieldProperty.type）

枚举值	说明
0	未知
1	文字
2	图标文字

---

字段值格式参考

在 add_records 和 update_records 中，field_values 的 value 格式因字段类型而异：

字段类型	值格式	示例
文本（1）	JSON Array of TextValue	[{"text": "内容", "type": "text"}]
数字（2）	number	42 或 3.14
复选框（3）	bool	true 或 false
日期（4）	string（毫秒时间戳）	"1720000000000"
图片（5）	JSON Array of ImageIDValue	[{"image_id": "图片id"}]
超链接（8）	JSON Array of UrlValue	[{"text": "链接文字", "type": "url", "link": "https://..."}]
多选（9）	JSON Array of OptionValue	[{"text": "选项1"}, {"text": "选项2"}]
进度（14）	number	75 或 75.5
电话（15）	string	"13800138000"
邮件（16）	string	"user@example.com"
单选（17）	JSON Array of OptionValue（单个）	[{"text": "选项文字"}]
关联（18）	array string	["record_id_1", "record_id_2"]
自动编号（25）	JSON(AutoNumberValue)	{"seq": "1", "text": "编号内容"}
货币（26）	double	99.99
百分比（28）	double	0.75（表示 75%）

TextValue 结构

{
  "text": "文本内容",
  "type": "text"
}

UrlValue 结构

{
  "text": "链接显示文字",
  "type": "url",
  "link": "https://example.com"
}

OptionValue 结构

{
  "id": "选项ID（可选）",
  "text": "选项文字",
  "style": 3
}

⚠️ 注意：写入记录时，单选/多选字段的 text 必须与字段属性中已定义的选项文字完全匹配，否则可能写入失败。

---

字段属性（Property）详细说明

NumberFieldProperty（数字字段属性）

{
  "decimal_places": 2,
  "use_separate": true
}

字段	类型	说明
decimal_places	uint32	小数点位数（精度）
use_separate	bool	是否使用千位符（如 1,000）

CheckboxFieldProperty（复选框字段属性）

{
  "checked": false
}

字段	类型	说明
checked	bool	新增记录时是否默认勾选

DateTimeFieldProperty（日期时间字段属性）

{
  "format": "yyyy-mm-dd",
  "auto_fill": false
}

字段	类型	说明
format	string	日期格式，支持格式见下方
auto_fill	bool	新建记录时是否自动填充当前时间

支持的日期格式：

格式字符串	示例
yyyy"年"m"月"d"日"	2018 年 4 月 20 日
yyyy-mm-dd	2018-04-20
yyyy/m/d	2018/4/20
m"月"d"日"	4 月 20 日
[$-804]yyyy"年"m"月"d"日" dddd	2018 年 4 月 20 日 星期五
yyyy"年"m"月"d"日" hh:mm	2018 年 4 月 20 日 14:00
yyyy-mm-dd hh:mm	2018-04-20 14:00
m/d/yyyy	4/20/2018
d/m/yyyy	20/4/2018

UrlFieldProperty（超链接字段属性）

{
  "type": 1
}

字段	类型	说明
type	uint32	展示样式：0-未知，1-文字，2-图标文字

SelectFieldProperty（多选字段属性）

{
  "options": [
    { "id": "opt_001", "text": "选项A", "style": 3 },
    { "id": "opt_002", "text": "选项B", "style": 4 }
  ],
  "is_multiple": true,
  "is_quick_add": false
}

字段	类型	说明
options	[]Option	选项列表
is_multiple	bool	是否多选（系统参数，用户无需设置）
is_quick_add	bool	是否允许填写时新增选项（系统参数，用户无需设置）

SingleSelectFieldProperty（单选字段属性）

结构与 SelectFieldProperty 相同，但只允许单选。

ProgressFieldProperty（进度字段属性）

{
  "decimal_places": 0
}

字段	类型	说明
decimal_places	uint32	小数位数

---

典型工作流示例

工作流一：从零创建表

步骤 1：获取文档的工作表列表
  → smartsheet.list_tables（获取 sheet_id）

步骤 2：为工作表添加字段
  → smartsheet.add_fields（添加：任务名称、优先级、负责人、截止日期、状态、进度）

步骤 3：批量添加任务记录
  → smartsheet.add_records（写入多条任务数据）

步骤 4：删除默认空行和默认列
  → smartsheet.list_records（获取建表时自动生成的空行 record_id 列表）
  → smartsheet.delete_records（传入空行 record_ids，批量删除默认空行）
  → smartsheet.list_fields（获取建表时自动生成的默认列 field_id 列表）
  → smartsheet.delete_fields（传入默认列 field_ids，批量删除默认列）

步骤 5：（可选）创建看板视图
  → smartsheet.add_view（view_type=2，按状态分组）

工作流二：查询并更新任务状态

步骤 1：列出工作表
  → smartsheet.list_tables（获取 sheet_id）

步骤 2：查询记录
  → smartsheet.list_records（获取 record_id 和当前字段值）

步骤 3：更新指定记录
  → smartsheet.update_records（传入 record_id 和新的字段值）

工作流三：读取数据并分析

步骤 1：列出工作表
  → smartsheet.list_tables

步骤 2：了解字段结构
  → smartsheet.list_fields（了解有哪些列及其类型）

步骤 3：分页读取所有记录
  → smartsheet.list_records（offset=0, limit=100）
  → 若 has_more=true，继续请求下一页（offset=100）

步骤 4：处理数据
  → 根据 field_values 中的数据进行统计分析

工作流四：清理过期数据

步骤 1：列出工作表
  → smartsheet.list_tables

步骤 2：查询需要删除的记录
  → smartsheet.list_records（获取目标 record_id 列表）

步骤 3：批量删除记录
  → smartsheet.delete_records（传入 record_ids 数组）

---

📌 提示：所有操作都需要先获取 file_id（智能表格文档 ID）和 sheet_id（工作表 ID）。 可通过 manage.search_file 搜索文档获取 file_id，再通过 smartsheet.list_tables 获取 sheet_id。

注意事项

• 前置条件：所有 smartsheet.* 工具都需要 file_id 和 sheet_id，操作前先调用 smartsheet.list_tables 获取 sheet_id
• 图片字段写入：向图片类型字段（field_type=5）写入数据时，需先调用 upload_image 工具上传图片获取 image_id，再以 [{"image_id": "xxx"}] 格式填入字段值
• 字段类型不可变：update_fields 时 field_type 不能修改，但必须传入原值；支持的字段类型详见字段类型枚举表
• 记录字段值格式：不同字段类型的值格式不同，详见上方"字段值格式参考"章节