# 智能表格（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[].is_visible` | bool | 工作表可见性 |
| `error`               | string | 错误信息，操作失败时返回 |
| `trace_id`            | string | 调用链追踪 ID |

**调用示例**：

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

**返回示例**：

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

**调用示例**：

```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 | `[{"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 结构

```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）。
> 可通过 `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` 不能修改，但必须传入原值；支持的字段类型详见字段类型枚举表
- **记录字段值格式**：不同字段类型的值格式不同，详见上方"字段值格式参考"章节