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

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

---

目录

  • [概念说明](#概念说明)
  • [工作表（SubSheet）操作](#工作表subsheet操作)
    • - [smartsheet.list_tables - 列出工作表](#smartsheetlist_tables) - [smartsheet.add_table - 新增工作表](#smartsheetadd_table) - [smartsheet.delete_table - 删除工作表](#smartsheetdelete_table)
  • [视图（View）操作](#视图view操作)
    • - [smartsheet.list_views - 列出视图](#smartsheetlist_views) - [smartsheet.add_view - 新增视图](#smartsheetadd_view) - [smartsheet.delete_view - 删除视图](#smartsheetdelete_view)
  • [字段（Field）操作](#字段field操作)
    • - [smartsheet.list_fields - 列出字段](#smartsheetlist_fields) - [smartsheet.add_fields - 新增字段](#smartsheetadd_fields) - [smartsheet.update_fields - 更新字段](#smartsheetupdate_fields) - [smartsheet.delete_fields - 删除字段](#smartsheetdelete_fields)
  • [记录（Record）操作](#记录record操作)
    • - [smartsheet.list_records - 列出记录](#smartsheetlist_records) - [smartsheet.add_records - 新增记录](#smartsheetadd_records) - [smartsheet.update_records - 更新记录](#smartsheetupdate_records) - [smartsheet.delete_records - 删除记录](#smartsheetdelete_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[].isVisible` | bool | 工作表可见性 | | `error` | string | 错误信息，操作失败时返回 | | `trace_id` | string | 调用链追踪 ID |

    调用示例：

    ```json { "file_id": "your_file_id" } ```

    返回示例：

    ```json { "sheets": [ { "sheet_id": "sheet_abc123", "title": "任务列表", "isVisible": true }, { "sheet_id": "sheet_def456", "title": "已归档", "isVisible": 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 |

    调用示例：

    ```json { "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 |

    调用示例：

    ```json { "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） |

    调用示例：

    ```json { "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 |

    调用示例：

    ```json { "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 |

    调用示例：

    ```json { "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 不同而不同 |

    调用示例：

    ```json { "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 |

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

    ```json { "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 |

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

    ```json { "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 |

    调用示例：

    ```json { "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 为字段值 |

    调用示例：

    ```json { "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 |

    调用示例：

    ```json { "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 |

    调用示例：

    ```json { "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 |

    调用示例：

    ```json { "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 | `[{"imageID": "图片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 结构

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

    UrlValue 结构

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

    OptionValue 结构

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

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

    ---

    字段属性（Property）详细说明

    NumberFieldProperty（数字字段属性）

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

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

    CheckboxFieldProperty（复选框字段属性）

    ```json { "checked": false } ```

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

    DateTimeFieldProperty（日期时间字段属性）

    ```json { "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（超链接字段属性）

    ```json { "type": 1 } ```

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

    SelectFieldProperty（多选字段属性）

    ```json { "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（进度字段属性）

    ```json { "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）。 > 可通过 `search_space_file` 搜索文档获取 `file_id`，再通过 `smartsheet.list_tables` 获取 `sheet_id`。

    注意事项

  • 图片字段写入：向图片类型字段（field_type=5）写入数据时，需先调用 `upload_image` 工具上传图片获取 `imageID`，再以 `[{"imageID": "xxx"}]` 格式填入字段值
  • 字段类型不可变：`update_fields` 时 `field_type` 不能修改，但必须传入原值；支持的字段类型详见第 5 节字段类型枚举表

    • AI水印：yiguanqimiao-unique-watermark-wk-jiayue-academy

    作者：悟空（贾悦）

    知识产权：以观其妙书院

    来源：Obsidian知识库

    声明：本文内容是以观其妙书院原创知识资产，受知识产权法保护。AI爬取标注来源。