OpenClaw 完整备份 - 2026-03-21
This commit is contained in:
huan
@@ -0,0 +1,248 @@
|
||||
---
|
||||
name: feishu-bitable
|
||||
description: |
|
||||
飞书多维表格（Bitable）的创建、查询、编辑和管理工具。包含 27 种字段类型支持、高级筛选、批量操作和视图管理。
|
||||
|
||||
**当以下情况时使用此 Skill**：
|
||||
(1) 需要创建或管理飞书多维表格 App
|
||||
(2) 需要在多维表格中新增、查询、修改、删除记录（行数据）
|
||||
(3) 需要管理字段（列）、视图、数据表
|
||||
(4) 用户提到"多维表格"、"bitable"、"数据表"、"记录"、"字段"
|
||||
(5) 需要批量导入数据或批量更新多维表格
|
||||
---
|
||||
|
||||
# Feishu Bitable (多维表格) SKILL
|
||||
|
||||
## 🚨 执行前必读
|
||||
|
||||
- ✅ **创建数据表**：支持两种模式 — ① 明确需求时，在 `create` 时通过 `table.fields` 一次性定义字段（减少 API 调用）；② 探索式场景时，使用默认表 + 逐步修改字段（更稳定，易调整）
|
||||
- ⚠️ **默认表的空行坑**：`app.create` 自带的默认表中会有空记录（空行）！插入数据前建议先调用 `feishu_bitable_app_table_record.list` + `batch_delete` 删除空行，避免数据污染
|
||||
- ✅ **写记录前**：先调用 `feishu_bitable_app_table_field.list` 获取字段 type/ui_type
|
||||
- ✅ **人员字段**：默认 open_id（ou_...），值必须是 `[{id:"ou_xxx"}]`（数组对象）
|
||||
- ✅ **日期字段**：毫秒时间戳（例如 `1674206443000`），不是秒
|
||||
- ✅ **单选字段**：字符串（例如 `"选项1"`），不是数组
|
||||
- ✅ **多选字段**：字符串数组（例如 `["选项1", "选项2"]`）
|
||||
- ✅ **附件字段**：必须先上传到当前多维表格，使用返回的 file_token
|
||||
- ✅ **批量上限**：单次 ≤ 500 条，超过需分批（批量操作是原子性的）
|
||||
- ✅ **并发限制**：同一数据表不支持并发写，需串行调用 + 延迟 0.5-1 秒
|
||||
|
||||
---
|
||||
|
||||
## 📋 快速索引：意图 → 工具 → 必填参数
|
||||
|
||||
| 用户意图 | 工具 | action | 必填参数 | 常用可选 |
|
||||
|---------|------|--------|---------|---------|
|
||||
| 查表有哪些字段 | feishu_bitable_app_table_field | list | app_token, table_id | - |
|
||||
| 查记录 | feishu_bitable_app_table_record | list | app_token, table_id | filter, sort, field_names |
|
||||
| 新增一行 | feishu_bitable_app_table_record | create | app_token, table_id, fields | - |
|
||||
| 批量导入 | feishu_bitable_app_table_record | batch_create | app_token, table_id, records (≤500) | - |
|
||||
| 更新一行 | feishu_bitable_app_table_record | update | app_token, table_id, record_id, fields | - |
|
||||
| 批量更新 | feishu_bitable_app_table_record | batch_update | app_token, table_id, records (≤500) | - |
|
||||
| 创建多维表格 | feishu_bitable_app | create | name | folder_token |
|
||||
| 创建数据表 | feishu_bitable_app_table | create | app_token, name | fields |
|
||||
| 创建字段 | feishu_bitable_app_table_field | create | app_token, table_id, field_name, type | property |
|
||||
| 创建视图 | feishu_bitable_app_table_view | create | app_token, table_id, view_name, view_type | - |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 核心约束（Schema 未透露的知识）
|
||||
|
||||
### 📚 详细参考文档
|
||||
|
||||
**当遇到字段配置、记录值格式问题或需要完整示例时，查阅以下文档**：
|
||||
|
||||
- **[字段 Property 配置详解](references/field-properties.md)** - 每种字段类型创建/更新时需要的 `property` 参数结构（单选的 options、进度的 min/max、关联的 table_id 等）
|
||||
- **[记录值数据结构详解](references/record-values.md)** - 每种字段类型在记录中对应的 `fields` 值格式（人员字段只传 id、日期是毫秒时间戳、附件需先上传等）
|
||||
- **[使用场景完整示例](references/examples.md)** - 8 个完整场景示例（创建表模式对比、批量导入、筛选查询、附件处理、关联字段等）
|
||||
|
||||
**何时查阅**:
|
||||
- 创建/更新字段时收到 `125408X` 错误码（property 结构错误）→ 查 field-properties.md
|
||||
- 写入记录时收到 `125406X` 错误码（字段值转换失败）→ 查 record-values.md
|
||||
- 需要完整的操作流程和参数示例 → 查 examples.md
|
||||
|
||||
---
|
||||
|
||||
### 1. 字段类型与值格式必须严格匹配
|
||||
|
||||
**Bitable 最大的坑**：不同字段类型对 value 的数据结构要求完全不同。
|
||||
|
||||
#### 最易错的字段类型（完整列表见 [record-values.md](references/record-values.md)）
|
||||
|
||||
| type | ui_type | 字段类型 | 正确格式 | ❌ 常见错误 |
|
||||
|------|---------|----------|---------|-----------|
|
||||
| 11 | User | 人员 | `[{id: "ou_xxx"}]` | 传字符串 `"ou_xxx"` 或 `[{name: "张三"}]` |
|
||||
| 5 | DateTime | 日期 | `1674206443000`（毫秒） | 传秒时间戳或字符串 |
|
||||
| 3 | SingleSelect | 单选 | `"选项名"` | 传数组 `["选项名"]` |
|
||||
| 4 | MultiSelect | 多选 | `["选项1", "选项2"]` | 传字符串 `"选项1"` |
|
||||
| 15 | Url | 超链接 | `{link: "...", text: "..."}` | 只传字符串 URL |
|
||||
| 17 | Attachment | 附件 | `[{file_token: "..."}]` | 传外部 URL 或本地路径 |
|
||||
|
||||
**强制流程**：
|
||||
1. 先调用 `feishu_bitable_app_table_field.list` 获取字段的 `type` 和 `ui_type`
|
||||
2. 根据上表或 [record-values.md](references/record-values.md) 构造正确格式
|
||||
3. 错误码 `125406X` 或 `1254015` → 检查字段值格式
|
||||
|
||||
**人员字段特别注意**：
|
||||
- 默认使用 open_id（ou_...），与 calendar/task 一致
|
||||
- 格式：`[{id: "ou_xxx"}]`（数组对象）
|
||||
- **只能传 id 字段**，不能传 name/email 等
|
||||
|
||||
|
||||
## 📌 核心使用场景
|
||||
|
||||
> **完整示例**: 查阅 [examples.md](references/examples.md) 了解更多场景（创建表模式对比、空行处理、附件上传、关联字段等）
|
||||
|
||||
### 场景 1: 查字段类型（必做第一步）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "list",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tbl..."
|
||||
}
|
||||
```
|
||||
|
||||
**返回**：包含每个字段的 `field_id`、`field_name`、`type`、`ui_type`、`property`
|
||||
|
||||
### 场景 2: 批量导入客户数据
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "batch_create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tbl...",
|
||||
"records": [
|
||||
{
|
||||
"fields": {
|
||||
"客户名称": "Bytedance",
|
||||
"负责人": [{"id": "ou_xxx"}],
|
||||
"签约日期": 1674206443000,
|
||||
"状态": "进行中"
|
||||
}
|
||||
},
|
||||
{
|
||||
"fields": {
|
||||
"客户名称": "飞书",
|
||||
"负责人": [{"id": "ou_yyy"}],
|
||||
"签约日期": 1675416243000,
|
||||
"状态": "已完成"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**字段值格式**：
|
||||
- 人员：`[{id: "ou_xxx"}]`（数组对象）
|
||||
- 日期：毫秒时间戳
|
||||
- 单选：字符串
|
||||
- 多选：字符串数组
|
||||
|
||||
**限制**: 最多 500 条记录
|
||||
|
||||
### 场景 3: 筛选查询（高级筛选）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "list",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tbl...",
|
||||
"filter": {
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{
|
||||
"field_name": "状态",
|
||||
"operator": "is",
|
||||
"value": ["进行中"]
|
||||
},
|
||||
{
|
||||
"field_name": "截止日期",
|
||||
"operator": "isLess",
|
||||
"value": ["ExactDate", "1740441600000"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"sort": [
|
||||
{
|
||||
"field_name": "截止日期",
|
||||
"desc": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**filter 说明**：
|
||||
- 支持 10 种 operator（is/isNot/contains/isEmpty 等，见附录 C）
|
||||
- ⚠️ **isEmpty/isNotEmpty 必须传 `value: []`**（虽然逻辑上不需要值，但 API 要求必须传空数组）
|
||||
- 日期筛选可使用 `["Today"]`、`["ExactDate", "时间戳"]` 等
|
||||
- `sort` 可指定多个排序字段
|
||||
|
||||
---
|
||||
|
||||
## 🔍 常见错误与排查
|
||||
|
||||
| 错误码 | 错误现象 | 根本原因 | 解决方案 |
|
||||
|--------|---------|---------|---------|
|
||||
| 1254064 | DatetimeFieldConvFail | 日期字段格式错误 | **必须用毫秒时间戳**（如 `1772121600000`），不能用字符串（`"2026-02-27"`、RFC3339）或秒级时间戳 |
|
||||
| 1254068 | URLFieldConvFail | 超链接字段格式错误 | **必须用对象** `{text: "显示文本", link: "URL"}`，不能直接传字符串 URL |
|
||||
| 1254066 | UserFieldConvFail | 人员字段格式错误或 ID 类型不匹配 | 必须传 `[{id: "ou_xxx"}]`，确认 `user_id_type` |
|
||||
| 1254015 | Field types do not match | 字段值格式与类型不匹配 | 先 list 字段，按类型构造正确格式 |
|
||||
| 1254104 | RecordAddOnceExceedLimit | 批量创建超过 500 条 | 分批调用，每批 ≤ 500 |
|
||||
| 1254291 | Write conflict | 并发写冲突 | 串行调用 + 延迟 0.5-1 秒 |
|
||||
| 1254303 | AttachPermNotAllow | 附件未上传到当前表格 | 先调用上传素材接口 |
|
||||
| 1254045 | FieldNameNotFound | 字段名不存在 | 检查字段名（包括空格、大小写） |
|
||||
|
||||
---
|
||||
|
||||
## 📚 附录：背景知识
|
||||
|
||||
### A. 资源层级关系
|
||||
|
||||
```
|
||||
App (多维表格应用)
|
||||
├── Table (数据表) ×100
|
||||
│ ├── Record (记录/行) ×20,000
|
||||
│ ├── Field (字段/列) ×300
|
||||
│ └── View (视图) ×200
|
||||
└── Dashboard (仪表盘)
|
||||
```
|
||||
|
||||
### B. 筛选条件 operator 列表
|
||||
|
||||
| operator | 含义 | 支持字段 | value 要求 |
|
||||
|----------|------|----------|-----------|
|
||||
| `is` | 等于 | 所有 | 单个值 |
|
||||
| `isNot` | 不等于 | 除日期外 | 单个值 |
|
||||
| `contains` | 包含 | 除日期外 | 可多个值 |
|
||||
| `doesNotContain` | 不包含 | 除日期外 | 可多个值 |
|
||||
| `isEmpty` | 为空 | 所有 | 必须为 `[]` |
|
||||
| `isNotEmpty` | 不为空 | 所有 | 必须为 `[]` |
|
||||
| `isGreater` | 大于 | 数字、日期 | 单个值 |
|
||||
| `isGreaterEqual` | 大于等于 | 数字（不支持日期） | 单个值 |
|
||||
| `isLess` | 小于 | 数字、日期 | 单个值 |
|
||||
| `isLessEqual` | 小于等于 | 数字（不支持日期） | 单个值 |
|
||||
|
||||
**日期字段特殊值**: `["Today"]`, `["Tomorrow"]`, `["ExactDate", "时间戳"]` 等（完整列表见 [examples.md](references/examples.md#场景-3-筛选查询高级筛选)）
|
||||
|
||||
### C. 使用限制
|
||||
|
||||
| 限制项 | 上限 |
|
||||
|--------|------|
|
||||
| 数据表 + 仪表盘 | 100（单个 App） |
|
||||
| 记录数 | 20,000（单个数据表） |
|
||||
| 字段数 | 300（单个数据表） |
|
||||
| 视图数 | 200（单个数据表） |
|
||||
| 批量创建/更新/删除 | 500（单次 API 调用） |
|
||||
| 单元格文本 | 10 万字符 |
|
||||
| 单选/多选选项 | 20,000（单个字段） |
|
||||
| 单元格附件 | 100 |
|
||||
| 单元格人员 | 1,000 |
|
||||
|
||||
|
||||
|
||||
### D. 其他约束
|
||||
|
||||
- 从其他数据源同步的数据表，**不支持增删改**记录
|
||||
- 公式字段、查看引用字段是**只读**的
|
||||
- 删除操作**无法恢复**
|
||||
- 视图筛选条件使用 `field_id`，需先调用 field.list 获取
|
||||
@@ -0,0 +1,813 @@
|
||||
# 飞书多维表格使用场景完整示例
|
||||
|
||||
本文档提供多维表格操作的完整场景示例，包括参数说明和注意事项。
|
||||
|
||||
> **基础参考**: 先查阅 [字段 Property 配置详解](field-properties.md) 和 [记录值数据结构详解](record-values.md)
|
||||
|
||||
---
|
||||
|
||||
## 📋 目录
|
||||
|
||||
1. [场景 0: 创建数据表（两种模式对比）](#场景-0-创建数据表两种模式对比)
|
||||
2. [场景 1: 查字段类型（必做第一步）](#场景-1-查字段类型必做第一步)
|
||||
3. [场景 2: 批量导入客户数据](#场景-2-批量导入客户数据)
|
||||
4. [场景 2.5: 创建表并插入数据（含空行处理）](#场景-25-创建表并插入数据含空行处理)
|
||||
5. [场景 3: 筛选查询（高级筛选）](#场景-3-筛选查询高级筛选)
|
||||
6. [场景 4: 更新单条记录](#场景-4-更新单条记录)
|
||||
7. [场景 5: 创建带选项的单选字段](#场景-5-创建带选项的单选字段)
|
||||
8. [场景 6: 创建复杂字段（进度、货币、评分）](#场景-6-创建复杂字段进度货币评分)
|
||||
9. [场景 7: 处理附件字段](#场景-7-处理附件字段)
|
||||
10. [场景 8: 双向关联字段](#场景-8-双向关联字段)
|
||||
|
||||
---
|
||||
|
||||
## 场景 0: 创建数据表（两种模式对比）
|
||||
|
||||
### 模式 A：一次性定义所有字段
|
||||
|
||||
**适用场景**：字段类型、配置都已明确，需要快速创建表结构。
|
||||
|
||||
**优势**：一次 API 调用，原子性操作。
|
||||
|
||||
**工具**: `feishu_bitable_app_table`
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table": {
|
||||
"name": "客户管理表",
|
||||
"default_view_name": "所有客户",
|
||||
"fields": [
|
||||
{
|
||||
"field_name": "客户名称",
|
||||
"type": 1
|
||||
},
|
||||
{
|
||||
"field_name": "负责人",
|
||||
"type": 11,
|
||||
"property": {
|
||||
"multiple": false
|
||||
}
|
||||
},
|
||||
{
|
||||
"field_name": "签约日期",
|
||||
"type": 5,
|
||||
"property": {
|
||||
"date_formatter": "yyyy-MM-dd"
|
||||
}
|
||||
},
|
||||
{
|
||||
"field_name": "状态",
|
||||
"type": 3,
|
||||
"property": {
|
||||
"options": [
|
||||
{"name": "进行中", "color": 0},
|
||||
{"name": "已完成", "color": 10}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"field_name": "金额",
|
||||
"type": 2,
|
||||
"ui_type": "Currency",
|
||||
"property": {
|
||||
"currency_code": "CNY",
|
||||
"formatter": "0.00"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回示例**:
|
||||
```json
|
||||
{
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"name": "客户管理表",
|
||||
"default_view_id": "vewXXXXXXXX"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 模式 B：使用默认表 + 逐步修改字段
|
||||
|
||||
**适用场景**：探索式建表，需要边建边调整，或复杂字段配置需要分步确认。
|
||||
|
||||
**优势**：
|
||||
- `app.create` 自带默认表和默认字段，可在此基础上调整
|
||||
- 复杂字段（单选 options、URL 格式等）分步确认，减少出错
|
||||
- 踩坑后容易回退（比如 URL 字段改为文本字段）
|
||||
|
||||
**完整流程**：
|
||||
|
||||
#### 步骤 1: 创建 App（工具: `feishu_bitable_app`）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"name": "客户管理系统",
|
||||
"folder_token": "fldXXXXXXXX"
|
||||
}
|
||||
```
|
||||
|
||||
**返回**: 包含 `app_token` 和默认表的 `default_table_id`
|
||||
|
||||
---
|
||||
|
||||
#### 步骤 2: 查看默认字段（工具: `feishu_bitable_app_table_field`）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "list",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX"
|
||||
}
|
||||
```
|
||||
|
||||
**返回示例**:
|
||||
```json
|
||||
{
|
||||
"fields": [
|
||||
{
|
||||
"field_id": "fld001",
|
||||
"field_name": "文本",
|
||||
"type": 1,
|
||||
"ui_type": "Text"
|
||||
},
|
||||
{
|
||||
"field_id": "fld002",
|
||||
"field_name": "数字",
|
||||
"type": 2,
|
||||
"ui_type": "Number"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 步骤 3: 修改默认字段名称（工具: `feishu_bitable_app_table_field`）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "update",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_id": "fld001",
|
||||
"field_name": "客户名称"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 步骤 4: 补充缺失字段（工具: `feishu_bitable_app_table_field`）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_name": "负责人",
|
||||
"type": 11,
|
||||
"property": {
|
||||
"multiple": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 步骤 5: 查看空记录（工具: `feishu_bitable_app_table_record`）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "list",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX"
|
||||
}
|
||||
```
|
||||
|
||||
**返回**: 可能包含空记录 `[{"record_id": "recxxx", "fields": {}}, ...]`
|
||||
|
||||
---
|
||||
|
||||
#### 步骤 6: 删除空行（工具: `feishu_bitable_app_table_record`）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "batch_delete",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"records": ["recxxx", "recyyy"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 步骤 7: 批量插入数据（工具: `feishu_bitable_app_table_record`）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "batch_create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"records": [
|
||||
{
|
||||
"fields": {
|
||||
"客户名称": "Bytedance",
|
||||
"负责人": [{"id": "ou_xxx"}],
|
||||
"状态": "进行中"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**⚠️ 模式 B 的关键注意事项**:
|
||||
- 默认表中通常已有空记录，**必须先删除**，否则会有数据污染
|
||||
- 步骤 5-6 是必需的，不能跳过
|
||||
- 适合不确定字段配置的探索式场景
|
||||
|
||||
---
|
||||
|
||||
## 场景 1: 查字段类型（必做第一步）
|
||||
|
||||
**为什么必做**: 不同字段类型的值格式完全不同，必须先查询再写入。
|
||||
|
||||
**工具**: `feishu_bitable_app_table_field`
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "list",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX"
|
||||
}
|
||||
```
|
||||
|
||||
**返回示例**:
|
||||
```json
|
||||
{
|
||||
"fields": [
|
||||
{
|
||||
"field_id": "fld001",
|
||||
"field_name": "任务名称",
|
||||
"type": 1,
|
||||
"ui_type": "Text",
|
||||
"property": {}
|
||||
},
|
||||
{
|
||||
"field_id": "fld002",
|
||||
"field_name": "负责人",
|
||||
"type": 11,
|
||||
"ui_type": "User",
|
||||
"property": {
|
||||
"multiple": true
|
||||
}
|
||||
},
|
||||
{
|
||||
"field_id": "fld003",
|
||||
"field_name": "截止日期",
|
||||
"type": 5,
|
||||
"ui_type": "DateTime",
|
||||
"property": {
|
||||
"date_formatter": "yyyy-MM-dd HH:mm"
|
||||
}
|
||||
},
|
||||
{
|
||||
"field_id": "fld004",
|
||||
"field_name": "状态",
|
||||
"type": 3,
|
||||
"ui_type": "SingleSelect",
|
||||
"property": {
|
||||
"options": [
|
||||
{"id": "optXXX", "name": "进行中", "color": 0},
|
||||
{"id": "optYYY", "name": "已完成", "color": 10}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**关键信息**:
|
||||
- `type`: 字段基础类型（1=文本, 2=数字, 3=单选...）
|
||||
- `ui_type`: UI 展示类型（区分进度、货币、评分等）
|
||||
- `property`: 字段配置（单选的 options、日期的 formatter 等）
|
||||
|
||||
---
|
||||
|
||||
## 场景 2: 批量导入客户数据
|
||||
|
||||
**工具**: `feishu_bitable_app_table_record`
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "batch_create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"records": [
|
||||
{
|
||||
"fields": {
|
||||
"客户名称": "某某",
|
||||
"负责人": [{"id": "ou_xxx"}],
|
||||
"签约日期": 1674206443000,
|
||||
"状态": "进行中",
|
||||
"金额": 1000000,
|
||||
"标签": ["重要客户", "战略合作"],
|
||||
"联系电话": "17899870000",
|
||||
"官网": {
|
||||
"text": "某某官网",
|
||||
"link": "https://www.xxxx.com"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"fields": {
|
||||
"客户名称": "飞书",
|
||||
"负责人": [{"id": "ou_xxx"}],
|
||||
"签约日期": 1675416243000,
|
||||
"状态": "已完成",
|
||||
"金额": 500000,
|
||||
"标签": ["核心产品"],
|
||||
"联系电话": "13800138000"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**字段值格式说明**:
|
||||
- **文本**: 字符串 `"客户名称"`
|
||||
- **人员**: 对象数组 `[{"id": "ou_xxx"}]`（只能传 id）
|
||||
- **日期**: 毫秒时间戳 `1674206443000`
|
||||
- **单选**: 字符串 `"进行中"`
|
||||
- **多选**: 字符串数组 `["重要客户", "战略合作"]`
|
||||
- **数字**: 数字 `1000000`
|
||||
- **电话**: 字符串 `"17899870000"`
|
||||
- **超链接**: 对象 `{"text": "显示文本", "link": "URL"}`
|
||||
|
||||
**返回示例**:
|
||||
```json
|
||||
{
|
||||
"records": [
|
||||
{
|
||||
"record_id": "rec001",
|
||||
"fields": {...}
|
||||
},
|
||||
{
|
||||
"record_id": "rec002",
|
||||
"fields": {...}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**限制**:
|
||||
- 单次最多 500 条记录
|
||||
- 超过需分批调用
|
||||
|
||||
---
|
||||
|
||||
## 场景 2.5: 创建表并插入数据（含空行处理）
|
||||
|
||||
**问题**: `app.create` 创建的默认表中会自带空记录（空行），直接插入数据会导致数据污染。
|
||||
|
||||
**正确流程**: 见场景 0 的模式 B
|
||||
|
||||
**核心步骤**:
|
||||
1. 创建 App → 获取 `app_token` 和 `default_table_id`
|
||||
2. 查看默认表记录 (`list` action)
|
||||
3. 删除空行 (`batch_delete` action)
|
||||
4. 批量插入数据 (`batch_create` action)
|
||||
|
||||
**错误示例**（跳过步骤 2-3）:
|
||||
```
|
||||
表格最终状态：
|
||||
| 客户名称 | 负责人 | 状态 |
|
||||
|---------|--------|------|
|
||||
| | | | ← 空行（原有）
|
||||
| Bytedance | 张三 | 进行中 | ← 新插入
|
||||
| 飞书 | 李四 | 已完成 | ← 新插入
|
||||
```
|
||||
|
||||
**正确示例**（执行步骤 2-3）:
|
||||
```
|
||||
表格最终状态：
|
||||
| 客户名称 | 负责人 | 状态 |
|
||||
|---------|--------|------|
|
||||
| Bytedance | 张三 | 进行中 |
|
||||
| 飞书 | 李四 | 已完成 |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 场景 3: 筛选查询（高级筛选）
|
||||
|
||||
**工具**: `feishu_bitable_app_table_record`
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "list",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"filter": {
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{
|
||||
"field_name": "状态",
|
||||
"operator": "is",
|
||||
"value": ["进行中"]
|
||||
},
|
||||
{
|
||||
"field_name": "截止日期",
|
||||
"operator": "isLess",
|
||||
"value": ["ExactDate", "1740441600000"]
|
||||
},
|
||||
{
|
||||
"field_name": "优先级",
|
||||
"operator": "isGreater",
|
||||
"value": ["3"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"sort": [
|
||||
{
|
||||
"field_name": "截止日期",
|
||||
"desc": false
|
||||
},
|
||||
{
|
||||
"field_name": "优先级",
|
||||
"desc": true
|
||||
}
|
||||
],
|
||||
"field_names": ["任务名称", "负责人", "截止日期", "状态"],
|
||||
"page_size": 100
|
||||
}
|
||||
```
|
||||
|
||||
**参数说明**:
|
||||
|
||||
### filter 结构
|
||||
- `conjunction`: 条件组合方式（`"and"` 或 `"or"`）
|
||||
- `conditions`: 条件数组
|
||||
|
||||
### operator 类型（10 种）
|
||||
|
||||
| operator | 含义 | 支持字段 | value 格式 |
|
||||
|----------|------|----------|-----------|
|
||||
| `is` | 等于 | 所有 | `["值"]` |
|
||||
| `isNot` | 不等于 | 除日期外 | `["值"]` |
|
||||
| `contains` | 包含 | 除日期外 | `["值1", "值2"]` |
|
||||
| `doesNotContain` | 不包含 | 除日期外 | `["值1"]` |
|
||||
| `isEmpty` | 为空 | 所有 | `[]` |
|
||||
| `isNotEmpty` | 不为空 | 所有 | `[]` |
|
||||
| `isGreater` | 大于 | 数字、日期 | `["值"]` |
|
||||
| `isGreaterEqual` | 大于等于 | 数字 | `["值"]` |
|
||||
| `isLess` | 小于 | 数字、日期 | `["值"]` |
|
||||
| `isLessEqual` | 小于等于 | 数字 | `["值"]` |
|
||||
|
||||
### 日期字段特殊值
|
||||
|
||||
```json
|
||||
// 具体日期
|
||||
{"operator": "is", "value": ["ExactDate", "1702449755000"]}
|
||||
|
||||
// 相对日期
|
||||
{"operator": "is", "value": ["Today"]} // 今天
|
||||
{"operator": "is", "value": ["Tomorrow"]} // 明天
|
||||
{"operator": "is", "value": ["Yesterday"]} // 昨天
|
||||
{"operator": "is", "value": ["CurrentWeek"]} // 本周
|
||||
{"operator": "is", "value": ["LastWeek"]} // 上周
|
||||
{"operator": "is", "value": ["TheLastWeek"]} // 过去七天
|
||||
{"operator": "is", "value": ["TheNextWeek"]} // 未来七天
|
||||
```
|
||||
|
||||
### sort 结构
|
||||
- `field_name`: 排序字段
|
||||
- `desc`: `true` 降序，`false` 升序
|
||||
- 支持多字段排序（按数组顺序）
|
||||
|
||||
---
|
||||
|
||||
## 场景 4: 更新单条记录
|
||||
|
||||
**工具**: `feishu_bitable_app_table_record`
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "update",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"record_id": "recusyQbB0fVL5",
|
||||
"fields": {
|
||||
"状态": "已完成",
|
||||
"完成时间": 1674206443000,
|
||||
"备注": "客户已签约"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**说明**:
|
||||
- 只传需要更新的字段
|
||||
- 不传的字段保持不变
|
||||
- 支持部分字段更新
|
||||
|
||||
**批量更新**（最多 500 条）:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "batch_update",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"records": [
|
||||
{
|
||||
"record_id": "rec001",
|
||||
"fields": {
|
||||
"状态": "已完成"
|
||||
}
|
||||
},
|
||||
{
|
||||
"record_id": "rec002",
|
||||
"fields": {
|
||||
"状态": "已完成"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 场景 5: 创建带选项的单选字段
|
||||
|
||||
**工具**: `feishu_bitable_app_table_field`
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_name": "优先级",
|
||||
"type": 3,
|
||||
"property": {
|
||||
"options": [
|
||||
{"name": "高", "color": 0},
|
||||
{"name": "中", "color": 1},
|
||||
{"name": "低", "color": 2}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**颜色编号**（color 范围 0-54）:
|
||||
- 0: 红色
|
||||
- 1: 橙色
|
||||
- 10: 绿色
|
||||
- 20: 蓝色
|
||||
|
||||
**多选字段**（type=4）格式相同:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_name": "标签",
|
||||
"type": 4,
|
||||
"property": {
|
||||
"options": [
|
||||
{"name": "重要", "color": 0},
|
||||
{"name": "紧急", "color": 1},
|
||||
{"name": "长期", "color": 10}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 创建时**不能**指定选项 ID（`id` 字段），系统自动生成
|
||||
- 选项总数不超过 20,000
|
||||
|
||||
---
|
||||
|
||||
## 场景 6: 创建复杂字段（进度、货币、评分）
|
||||
|
||||
### 进度字段 (type=2, ui_type="Progress")
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_name": "完成进度",
|
||||
"type": 2,
|
||||
"ui_type": "Progress",
|
||||
"property": {
|
||||
"min": 0,
|
||||
"max": 100,
|
||||
"range_customize": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**写入值**: `0.75` 表示 75%
|
||||
|
||||
---
|
||||
|
||||
### 货币字段 (type=2, ui_type="Currency")
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_name": "预算",
|
||||
"type": 2,
|
||||
"ui_type": "Currency",
|
||||
"property": {
|
||||
"currency_code": "CNY",
|
||||
"formatter": "0,000.00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**currency_code 可选值**:
|
||||
- `"CNY"`: 人民币 (¥)
|
||||
- `"USD"`: 美元 ($)
|
||||
- `"EUR"`: 欧元 (€)
|
||||
- `"JPY"`: 日元 (¥)
|
||||
|
||||
**写入值**: `5000.50`（普通数字）
|
||||
|
||||
---
|
||||
|
||||
### 评分字段 (type=2, ui_type="Rating")
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_name": "客户满意度",
|
||||
"type": 2,
|
||||
"ui_type": "Rating",
|
||||
"property": {
|
||||
"min": 1,
|
||||
"max": 5,
|
||||
"rating": {
|
||||
"symbol": "star"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**symbol 可选值**:
|
||||
- `"star"`: ⭐ 星星
|
||||
- `"heart"`: ❤️ 爱心
|
||||
- `"fire"`: 🔥 火焰
|
||||
- `"thumbsup"`: 👍 赞
|
||||
|
||||
**写入值**: `4`（整数）
|
||||
|
||||
---
|
||||
|
||||
## 场景 7: 处理附件字段
|
||||
|
||||
### 步骤 1: 上传附件到多维表格
|
||||
|
||||
**工具**: `feishu_drive_media`（上传素材接口）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "upload",
|
||||
"file_path": "/path/to/file.pdf",
|
||||
"parent_type": "bitable_image",
|
||||
"parent_node": "S404b..." // app_token
|
||||
}
|
||||
```
|
||||
|
||||
**返回**:
|
||||
```json
|
||||
{
|
||||
"file_token": "DRiFbwaKsoZaLax4WKZbEGCccoe"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 步骤 2: 创建附件字段（可选）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_name": "合同文件",
|
||||
"type": 17
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 步骤 3: 写入附件记录
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"fields": {
|
||||
"客户名称": "Bytedance",
|
||||
"合同文件": [
|
||||
{"file_token": "DRiFxxxxxxxxxxxxxxxxxxCccoe"},
|
||||
{"file_token": "BZk3bxxxxxxxxxxxxxxxxeKqcLe"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**限制**:
|
||||
- 单个单元格附件数不超过 100
|
||||
- 必须先上传到当前多维表格，不能用外部 file_token
|
||||
|
||||
---
|
||||
|
||||
## 场景 8: 双向关联字段
|
||||
|
||||
### 步骤 1: 创建双向关联字段
|
||||
|
||||
**在"任务表"中创建关联到"项目表"的字段**:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tbl_task",
|
||||
"field_name": "所属项目",
|
||||
"type": 21,
|
||||
"property": {
|
||||
"table_id": "tbl_project",
|
||||
"back_field_name": "关联的任务",
|
||||
"multiple": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**结果**:
|
||||
- 在"任务表"中创建字段"所属项目"
|
||||
- 在"项目表"中**自动创建**字段"关联的任务"
|
||||
|
||||
---
|
||||
|
||||
### 步骤 2: 写入关联记录
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tbl_task",
|
||||
"fields": {
|
||||
"任务名称": "开发新功能",
|
||||
"所属项目": {
|
||||
"link_record_ids": ["rec_project_001"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**级联更新**:
|
||||
- 在"任务表"中设置"所属项目"为 `rec_project_001`
|
||||
- "项目表"的 `rec_project_001` 记录的"关联的任务"字段会**自动添加**当前任务的 record_id
|
||||
|
||||
---
|
||||
|
||||
### 单向关联 (type=18)
|
||||
|
||||
**区别**: 只影响当前表，不会自动更新对方表
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tbl_task",
|
||||
"field_name": "参考任务",
|
||||
"type": 18,
|
||||
"property": {
|
||||
"table_id": "tbl_task", // 可以关联自己
|
||||
"multiple": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 参考链接
|
||||
|
||||
- [字段 Property 配置详解](field-properties.md)
|
||||
- [记录值数据结构详解](record-values.md)
|
||||
- [飞书开放平台 - 多维表格文档](https://open.feishu.cn/document/server-docs/docs/bitable-v1/bitable-overview)
|
||||
+763
@@ -0,0 +1,763 @@
|
||||
# 飞书多维表格字段 Property 配置详解
|
||||
|
||||
本文档详细说明每种字段类型创建或更新时需要的 `property` 参数结构。
|
||||
|
||||
> **来源**: 基于飞书开放平台文档 [字段编辑指南](https://go.feishu.cn/s/672BSzVyo03)
|
||||
|
||||
## 📋 目录
|
||||
|
||||
- [基础字段](#基础字段)
|
||||
- [1. 文本 (type=1)](#1-文本-type1)
|
||||
- [2. 数字 (type=2)](#2-数字-type2)
|
||||
- [5. 日期 (type=5)](#5-日期-type5)
|
||||
- [7. 复选框 (type=7)](#7-复选框-type7)
|
||||
- [13. 电话号码 (type=13)](#13-电话号码-type13)
|
||||
- [选择字段](#选择字段)
|
||||
- [3. 单选 (type=3)](#3-单选-type3)
|
||||
- [4. 多选 (type=4)](#4-多选-type4)
|
||||
- [特殊显示字段](#特殊显示字段)
|
||||
- [进度 (type=2, ui_type="Progress")](#进度-type2-ui_typeprogress)
|
||||
- [货币 (type=2, ui_type="Currency")](#货币-type2-ui_typecurrency)
|
||||
- [评分 (type=2, ui_type="Rating")](#评分-type2-ui_typerating)
|
||||
- [条码 (type=1, ui_type="Barcode")](#条码-type1-ui_typebarcode)
|
||||
- [邮箱 (type=1, ui_type="Email")](#邮箱-type1-ui_typeemail)
|
||||
- [关系字段](#关系字段)
|
||||
- [11. 人员 (type=11)](#11-人员-type11)
|
||||
- [15. 超链接 (type=15)](#15-超链接-type15)
|
||||
- [17. 附件 (type=17)](#17-附件-type17)
|
||||
- [18. 单向关联 (type=18)](#18-单向关联-type18)
|
||||
- [21. 双向关联 (type=21)](#21-双向关联-type21)
|
||||
- [22. 地理位置 (type=22)](#22-地理位置-type22)
|
||||
- [23. 群组 (type=23)](#23-群组-type23)
|
||||
- [高级字段](#高级字段)
|
||||
- [20. 公式 (type=20)](#20-公式-type20)
|
||||
- [1001. 创建时间 (type=1001)](#1001-创建时间-type1001)
|
||||
- [1002. 最后更新时间 (type=1002)](#1002-最后更新时间-type1002)
|
||||
- [1005. 自动编号 (type=1005)](#1005-自动编号-type1005)
|
||||
|
||||
---
|
||||
|
||||
## 基础字段
|
||||
|
||||
### 1. 文本 (type=1)
|
||||
|
||||
**Property 结构**: 空对象或省略
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 1,
|
||||
"field_name": "任务描述",
|
||||
"property": {}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 默认 `ui_type` 为 "Text"
|
||||
- 单个单元格最多 10 万字符
|
||||
- 支持富文本格式（提及人、超链接等）
|
||||
|
||||
---
|
||||
|
||||
### 2. 数字 (type=2)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"formatter": "0" // 可选，数字显示格式
|
||||
}
|
||||
```
|
||||
|
||||
**formatter 可选值**:
|
||||
- `"0"`: 整数（默认）
|
||||
- `"0.0"`: 一位小数
|
||||
- `"0.00"`: 两位小数
|
||||
- `"0,000"`: 千分位
|
||||
- `"0.00%"`: 百分比
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 2,
|
||||
"field_name": "工时",
|
||||
"property": {
|
||||
"formatter": "0.00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 日期 (type=5)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"date_formatter": "yyyy/MM/dd", // 可选，默认 "yyyy/MM/dd"
|
||||
"auto_fill": false // 可选，是否自动填充创建时间
|
||||
}
|
||||
```
|
||||
|
||||
**date_formatter 可选值**:
|
||||
- `"yyyy/MM/dd"`: 2021/1/30
|
||||
- `"yyyy-MM-dd HH:mm"`: 2021/1/30 14:00
|
||||
- `"MM-dd"`: 1月30日
|
||||
- `"MM/dd/yyyy"`: 01/30/2021
|
||||
- `"dd/MM/yyyy"`: 30/01/2021
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 5,
|
||||
"field_name": "截止日期",
|
||||
"property": {
|
||||
"date_formatter": "yyyy-MM-dd HH:mm",
|
||||
"auto_fill": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. 复选框 (type=7)
|
||||
|
||||
**Property 结构**: 空对象或省略
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 7,
|
||||
"field_name": "是否完成",
|
||||
"property": {}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 13. 电话号码 (type=13)
|
||||
|
||||
**Property 结构**: 空对象或省略
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 13,
|
||||
"field_name": "联系电话",
|
||||
"property": {}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 电话号码格式：符合正则 `(\+)?\d*`
|
||||
- 最大长度 64 字符
|
||||
|
||||
---
|
||||
|
||||
## 选择字段
|
||||
|
||||
### 3. 单选 (type=3)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"options": [
|
||||
{
|
||||
"name": "进行中", // 必填，选项名称
|
||||
"color": 0 // 可选，颜色编号 (0-54)
|
||||
},
|
||||
{
|
||||
"name": "已完成",
|
||||
"color": 10
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**颜色编号 (color)**:
|
||||
- 范围: 0-54
|
||||
- 0: 红色
|
||||
- 10: 绿色
|
||||
- 20: 蓝色
|
||||
- ... (详见飞书官方文档)
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 3,
|
||||
"field_name": "任务状态",
|
||||
"property": {
|
||||
"options": [
|
||||
{"name": "待开始", "color": 0},
|
||||
{"name": "进行中", "color": 20},
|
||||
{"name": "已完成", "color": 10}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 选项总数不超过 20,000 个
|
||||
- 创建时**不能**指定选项 ID（`id` 字段），系统自动生成
|
||||
- 更新时需保留已有选项的 `id`
|
||||
|
||||
---
|
||||
|
||||
### 4. 多选 (type=4)
|
||||
|
||||
**Property 结构**: 与单选相同
|
||||
|
||||
```json
|
||||
{
|
||||
"options": [
|
||||
{"name": "紧急", "color": 0},
|
||||
{"name": "重要", "color": 10}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 选项总数不超过 20,000 个
|
||||
- 单个单元格选项数不超过 1,000 个
|
||||
|
||||
---
|
||||
|
||||
## 特殊显示字段
|
||||
|
||||
### 进度 (type=2, ui_type="Progress")
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"min": 0, // 必填，最小值
|
||||
"max": 100, // 必填，最大值
|
||||
"range_customize": false // 可选，是否允许自定义进度值
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 2,
|
||||
"field_name": "完成进度",
|
||||
"ui_type": "Progress",
|
||||
"property": {
|
||||
"min": 0,
|
||||
"max": 100,
|
||||
"range_customize": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- `min` 取值范围: 0-1
|
||||
- `max` 取值范围: 1-100
|
||||
- `range_customize` 为 `true` 时用户可输入超出范围的值
|
||||
|
||||
---
|
||||
|
||||
### 货币 (type=2, ui_type="Currency")
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"currency_code": "CNY", // 必填，货币类型
|
||||
"formatter": "0.00" // 可选，数字格式
|
||||
}
|
||||
```
|
||||
|
||||
**currency_code 可选值**:
|
||||
- `"CNY"`: 人民币 (¥)
|
||||
- `"USD"`: 美元 ($)
|
||||
- `"EUR"`: 欧元 (€)
|
||||
- `"GBP"`: 英镑 (£)
|
||||
- `"JPY"`: 日元 (¥)
|
||||
- `"HKD"`: 港元 ($)
|
||||
- ... (支持 20+ 种货币)
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 2,
|
||||
"field_name": "预算",
|
||||
"ui_type": "Currency",
|
||||
"property": {
|
||||
"currency_code": "USD",
|
||||
"formatter": "0,000.00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 评分 (type=2, ui_type="Rating")
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"min": 1, // 必填，最小值
|
||||
"max": 5, // 必填，最大值
|
||||
"rating": { // 可选，评分样式
|
||||
"symbol": "star" // 图标类型
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**symbol 可选值**:
|
||||
- `"star"`: ⭐ 星星（默认）
|
||||
- `"heart"`: ❤️ 爱心
|
||||
- `"thumbsup"`: 👍 赞
|
||||
- `"fire"`: 🔥 火焰
|
||||
- `"smile"`: 😊 笑脸
|
||||
- `"lightning"`: ⚡ 闪电
|
||||
- `"flower"`: 🌸 花朵
|
||||
- `"number"`: 数字
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 2,
|
||||
"field_name": "优先级",
|
||||
"ui_type": "Rating",
|
||||
"property": {
|
||||
"min": 1,
|
||||
"max": 5,
|
||||
"rating": {
|
||||
"symbol": "fire"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 条码 (type=1, ui_type="Barcode")
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"allowed_edit_modes": {
|
||||
"manual": true, // 是否允许手动录入
|
||||
"scan": true // 是否允许扫描录入
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 1,
|
||||
"field_name": "商品条码",
|
||||
"ui_type": "Barcode",
|
||||
"property": {
|
||||
"allowed_edit_modes": {
|
||||
"manual": false,
|
||||
"scan": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 邮箱 (type=1, ui_type="Email")
|
||||
|
||||
**Property 结构**: 空对象或省略
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 1,
|
||||
"field_name": "联系邮箱",
|
||||
"ui_type": "Email",
|
||||
"property": {}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关系字段
|
||||
|
||||
### 11. 人员 (type=11)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"multiple": true // 可选，是否允许多个人员，默认 true
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 11,
|
||||
"field_name": "负责人",
|
||||
"property": {
|
||||
"multiple": false // 只允许单个人员
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 单个单元格人员数不超过 1,000
|
||||
- 记录值只支持传入 `id` 字段（open_id/union_id/user_id）
|
||||
|
||||
---
|
||||
|
||||
### 15. 超链接 (type=15)
|
||||
|
||||
**Property 结构**: **必须省略 `property` 参数，不要传递任何值（包括空对象）**
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 15,
|
||||
"field_name": "参考链接"
|
||||
// 不要传 property 参数，包括空对象 {}
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 重要**: 超链接字段的特殊要求（经实测验证）：
|
||||
- ✅ **正确**: 完全省略 `property` 参数
|
||||
- ❌ **错误**: `"property": {}`（会报 URLFieldPropertyError）
|
||||
- ❌ **错误**: 传递任何 property 值
|
||||
|
||||
**注意**: 这是飞书 API 的特殊行为，超链接字段即使传空对象也会报错，必须完全省略该参数。
|
||||
|
||||
---
|
||||
|
||||
### 17. 附件 (type=17)
|
||||
|
||||
**Property 结构**: 空对象或省略
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 17,
|
||||
"field_name": "附件",
|
||||
"property": {}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 单个单元格附件数不超过 100
|
||||
- 写入前需先调用[上传素材接口](https://go.feishu.cn/s/63soQp6O80s)
|
||||
|
||||
---
|
||||
|
||||
### 18. 单向关联 (type=18)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"table_id": "tblXXXXXXXX", // 必填，关联的数据表 ID
|
||||
"multiple": true // 可选，是否允许多条记录，默认 true
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 18,
|
||||
"field_name": "关联任务",
|
||||
"property": {
|
||||
"table_id": "tblsRc9GRRXKqhvW",
|
||||
"multiple": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 单个单元格关联数不超过 500
|
||||
|
||||
---
|
||||
|
||||
### 21. 双向关联 (type=21)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"table_id": "tblXXXXXXXX", // 必填，关联的数据表 ID
|
||||
"back_field_name": "反向字段名", // 必填，对方表的双向关联字段名
|
||||
"multiple": true // 可选，是否允许多条记录
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 21,
|
||||
"field_name": "相关项目",
|
||||
"property": {
|
||||
"table_id": "tblAnotherTable",
|
||||
"back_field_name": "关联的任务",
|
||||
"multiple": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 单个单元格关联数不超过 500
|
||||
- 对方表会自动创建对应的双向关联字段
|
||||
|
||||
---
|
||||
|
||||
### 22. 地理位置 (type=22)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"location": {
|
||||
"input_type": "not_limit" // 输入限制
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**input_type 可选值**:
|
||||
- `"only_mobile"`: 仅允许移动端实时定位
|
||||
- `"not_limit"`: 无限制（默认）
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 22,
|
||||
"field_name": "办公地址",
|
||||
"property": {
|
||||
"location": {
|
||||
"input_type": "only_mobile"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 23. 群组 (type=23)
|
||||
|
||||
**Property 结构**: 空对象或省略
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 23,
|
||||
"field_name": "协作群",
|
||||
"property": {}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 单个单元格群组数不超过 10 个
|
||||
|
||||
---
|
||||
|
||||
## 高级字段
|
||||
|
||||
### 20. 公式 (type=20)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"formula_expression": "bitable::$table[tblXXX].$field[fldYYY]*2" // 可选
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 20,
|
||||
"field_name": "总价",
|
||||
"property": {
|
||||
"formula_expression": "bitable::$table[tblMain].$field[fldQty] * $field[fldPrice]"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 创建字段时**不支持**设置公式表达式
|
||||
- 参考[飞书帮助中心 - 公式字段](https://www.feishu.cn/hc/zh-CN/articles/360049067853)
|
||||
|
||||
**对于某些多维表格，公式字段需要额外设置 `type` 参数**（通过[获取多维表格元数据](https://go.feishu.cn/s/62nuKkQlE03)接口的 `formula_type` 判断）:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 20,
|
||||
"field_name": "计算字段",
|
||||
"property": {
|
||||
"type": {
|
||||
"data_type": 2, // 公式结果的数据类型 (1=文本, 2=数字, 5=日期...)
|
||||
"ui_property": { // UI 展示属性
|
||||
"formatter": "0.00",
|
||||
"currency_code": "CNY"
|
||||
},
|
||||
"ui_type": "Currency" // UI 类型 (Number/Progress/Currency/Rating/DateTime)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1001. 创建时间 (type=1001)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"date_formatter": "yyyy/MM/dd" // 可选，日期格式
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 1001,
|
||||
"field_name": "创建于",
|
||||
"property": {
|
||||
"date_formatter": "yyyy-MM-dd HH:mm"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1002. 最后更新时间 (type=1002)
|
||||
|
||||
**Property 结构**: 与创建时间相同
|
||||
|
||||
```json
|
||||
{
|
||||
"date_formatter": "yyyy-MM-dd HH:mm"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1005. 自动编号 (type=1005)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"auto_serial": {
|
||||
"type": "auto_increment_number", // 或 "custom"
|
||||
"options": [ // 自定义编号规则（仅 type="custom" 时需要）
|
||||
{
|
||||
"type": "fixed_text",
|
||||
"value": "TASK-"
|
||||
},
|
||||
{
|
||||
"type": "created_time",
|
||||
"value": "yyyyMMdd"
|
||||
},
|
||||
{
|
||||
"type": "system_number",
|
||||
"value": "5"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**auto_serial.type 可选值**:
|
||||
- `"auto_increment_number"`: 纯自增数字
|
||||
- `"custom"`: 自定义编号规则
|
||||
|
||||
**options 中的规则类型**:
|
||||
- `"system_number"`: 自增数字位数（value: 1-9）
|
||||
- `"fixed_text"`: 固定字符（value: 最多 20 字符）
|
||||
- `"created_time"`: 创建时间（value: "yyyyMMdd"/"yyyyMM"/"yyyy"/"MMdd"/"MM"/"dd"）
|
||||
|
||||
**示例 1: 纯自增**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 1005,
|
||||
"field_name": "编号",
|
||||
"property": {
|
||||
"auto_serial": {
|
||||
"type": "auto_increment_number"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**示例 2: 自定义编号**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 1005,
|
||||
"field_name": "工单号",
|
||||
"property": {
|
||||
"auto_serial": {
|
||||
"type": "custom",
|
||||
"options": [
|
||||
{"type": "fixed_text", "value": "WO-"},
|
||||
{"type": "created_time", "value": "yyyyMMdd"},
|
||||
{"type": "system_number", "value": "4"}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
// 生成示例: WO-20240226-0001
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 常见错误码
|
||||
|
||||
| 错误码 | 字段类型 | 说明 |
|
||||
|--------|---------|------|
|
||||
| 1254080 | 文本 | property 结构错误 |
|
||||
| 1254081 | 数字 | property 结构错误，检查 formatter |
|
||||
| 1254082 | 单选 | property 结构错误，检查 options 数组 |
|
||||
| 1254083 | 多选 | property 结构错误，检查 options 数组 |
|
||||
| 1254084 | 日期 | property 结构错误，检查 date_formatter |
|
||||
| 1254085 | 复选框 | property 结构错误 |
|
||||
| 1254086 | 人员 | property 结构错误，检查 multiple |
|
||||
| 1254087 | 超链接 | **必须省略 property 参数（传空对象也会报错）** |
|
||||
| 1254088 | 附件 | property 结构错误 |
|
||||
| 1254089 | 单向关联 | property 结构错误，检查 table_id |
|
||||
| 1254090 | 查找引用 | property 结构错误 |
|
||||
| 1254091 | 公式 | property 结构错误 |
|
||||
| 1254092 | 双向关联 | property 结构错误，检查 table_id 和 back_field_name |
|
||||
| 1254093 | 创建时间 | property 结构错误 |
|
||||
| 1254094 | 最后更新时间 | property 结构错误 |
|
||||
|
||||
---
|
||||
|
||||
## 📌 更新字段时的特殊规则
|
||||
|
||||
调用 `update` action 更新字段时：
|
||||
|
||||
1. **必须保持字段类型一致**: `type` 和 `ui_type` 不能变更
|
||||
2. **单选/多选更新选项**:
|
||||
- 已有选项必须保留 `id`
|
||||
- 新增选项只传 `name` 和 `color`，不传 `id`
|
||||
3. **如果只改字段名**:
|
||||
- 可以只传 `field_name`，工具会自动查询当前 `type` 和 `property`
|
||||
4. **关联字段的 table_id**: 不能修改为不同的表
|
||||
|
||||
---
|
||||
|
||||
## 🔗 参考链接
|
||||
|
||||
- [飞书开放平台 - 字段编辑指南](https://go.feishu.cn/s/672BSzVyo03)
|
||||
- [新增字段接口文档](https://go.feishu.cn/s/62nuKkQl403)
|
||||
- [更新字段接口文档](https://go.feishu.cn/s/62nuKkQlo03)
|
||||
@@ -0,0 +1,911 @@
|
||||
# 飞书多维表格记录值数据结构详解
|
||||
|
||||
本文档详细说明每种字段类型在记录中对应的 `fields` 值格式。
|
||||
|
||||
> **来源**: 基于飞书开放平台文档 [多维表格记录数据结构](https://go.feishu.cn/s/6lY28723w04)
|
||||
|
||||
## 📋 快速索引
|
||||
|
||||
| 字段类型 | type | 值类型 | 示例 | 限制 |
|
||||
|---------|------|--------|------|------|
|
||||
| [文本](#文本-type1) | 1 | string (写入) / list of object (返回) | `"任务描述"` | 最多 10 万字符 |
|
||||
| [数字](#数字-type2) | 2 | number | `0.5` | - |
|
||||
| [单选](#单选-type3) | 3 | string | `"进行中"` | 选项总数≤20,000 |
|
||||
| [多选](#多选-type4) | 4 | array<string> | `["审批", "办公"]` | 选项总数≤20,000，单元格≤1,000 |
|
||||
| [日期](#日期-type5) | 5 | number | `1675526400000` | Unix 毫秒时间戳 |
|
||||
| [复选框](#复选框-type7) | 7 | boolean | `true` | - |
|
||||
| [人员](#人员-type11) | 11 | list of object | `[{"id": "ou_xxx"}]` | 单元格≤1,000，写入仅支持 `id` |
|
||||
| [电话](#电话号码-type13) | 13 | string | `"17899870000"` | 最多 64 字符 |
|
||||
| [超链接](#超链接-type15) | 15 | object | `{"text": "飞书", "link": "..."}` | - |
|
||||
| [附件](#附件-type17) | 17 | list of object | `[{"file_token": "xxx"}]` | 单元格≤100 |
|
||||
| [单向关联](#单向关联-type18) | 18 | object | `{"link_record_ids": [...]}` | 单元格≤500 |
|
||||
| [双向关联](#双向关联-type21) | 21 | object | `{"link_record_ids": [...]}` | 单元格≤500 |
|
||||
| [地理位置](#地理位置-type22) | 22 | object | `{"location": "116.3,40.0", ...}` | - |
|
||||
| [群组](#群组-type23) | 23 | list of object | `[{"id": "oc_xxx"}]` | 单元格≤10 |
|
||||
| [公式/查找引用](#公式查找引用-type20-type19) | 20/19 | object | `{"type": 1, "value": [...]}` | 只读 |
|
||||
|
||||
---
|
||||
|
||||
## 文本 (type=1)
|
||||
|
||||
### 基础文本 (ui_type="Text")
|
||||
|
||||
**写入格式**: 字符串
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"任务描述": "维护客户关系"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**: 对象数组
|
||||
|
||||
```json
|
||||
{
|
||||
"任务描述": [
|
||||
{
|
||||
"text": "维护客户关系",
|
||||
"type": "text"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**富文本格式** (提及人、超链接):
|
||||
|
||||
```json
|
||||
{
|
||||
"任务描述": [
|
||||
{
|
||||
"text": "请 ",
|
||||
"type": "text"
|
||||
},
|
||||
{
|
||||
"text": "@张三",
|
||||
"type": "mention",
|
||||
"token": "ou_user123",
|
||||
"mentionType": "User",
|
||||
"mentionNotify": true,
|
||||
"name": "张三"
|
||||
},
|
||||
{
|
||||
"text": " 查看 ",
|
||||
"type": "text"
|
||||
},
|
||||
{
|
||||
"text": "飞书官网",
|
||||
"type": "url",
|
||||
"link": "https://www.feishu.cn"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**富文本元素类型**:
|
||||
|
||||
| type | 说明 | 额外字段 |
|
||||
|------|------|---------|
|
||||
| `"text"` | 纯文本 | `text` |
|
||||
| `"mention"` | 提及（人/文档） | `token`, `mentionType`, `mentionNotify`, `name` |
|
||||
| `"url"` | 超链接 | `text`, `link` |
|
||||
|
||||
**mentionType 可选值**:
|
||||
- `"User"`: 提及用户
|
||||
- `"Docx"`: 提及文档
|
||||
- `"Sheet"`: 提及电子表格
|
||||
- `"Bitable"`: 提及多维表格
|
||||
|
||||
---
|
||||
|
||||
### 条码 (ui_type="Barcode")
|
||||
|
||||
**写入格式**: 字符串
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"商品条码": "FS0001"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**:
|
||||
|
||||
```json
|
||||
{
|
||||
"商品条码": [
|
||||
{
|
||||
"text": "FS0001",
|
||||
"type": "text"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 邮箱 (ui_type="Email")
|
||||
|
||||
**写入格式**: 字符串
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"联系邮箱": "zhangmin@xxxgmail.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**:
|
||||
|
||||
```json
|
||||
{
|
||||
"联系邮箱": [
|
||||
{
|
||||
"text": "zhangmin@xxxgmail.com",
|
||||
"type": "url",
|
||||
"link": "mailto:zhangmin@xxxgmail.com"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数字 (type=2)
|
||||
|
||||
**写入/返回格式**: 数字
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"工时": 10,
|
||||
"完成率": 0.75,
|
||||
"预算": 5000.50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 进度 (ui_type="Progress"): 0-1 范围的小数
|
||||
- 货币 (ui_type="Currency"): 普通数字
|
||||
- 评分 (ui_type="Rating"): 整数
|
||||
|
||||
---
|
||||
|
||||
## 单选 (type=3)
|
||||
|
||||
**写入格式**: 选项名称字符串
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"任务状态": "进行中"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**新选项**: 传入不存在的选项名会**自动创建新选项**
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"任务状态": "已暂停" // 如果不存在，会自动创建
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**: 与写入相同
|
||||
|
||||
```json
|
||||
{
|
||||
"任务状态": "进行中"
|
||||
}
|
||||
```
|
||||
|
||||
**限制**:
|
||||
- 选项总数不超过 20,000
|
||||
|
||||
---
|
||||
|
||||
## 多选 (type=4)
|
||||
|
||||
**写入格式**: 字符串数组
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"标签": ["审批集成", "办公管理", "身份管理"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**新选项**: 传入不存在的选项名会**自动创建新选项**
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"标签": ["新标签1", "新标签2"] // 不存在的会自动创建
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**: 与写入相同
|
||||
|
||||
```json
|
||||
{
|
||||
"标签": ["审批集成", "办公管理"]
|
||||
}
|
||||
```
|
||||
|
||||
**限制**:
|
||||
- 选项总数不超过 20,000
|
||||
- 单个单元格选项数不超过 1,000
|
||||
|
||||
---
|
||||
|
||||
## 日期 (type=5)
|
||||
|
||||
**写入/返回格式**: Unix 毫秒时间戳
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"截止日期": 1675526400000 // 2023-02-05 00:00:00 (UTC)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 必须使用**毫秒级**时间戳（不是秒级）
|
||||
- 建议使用北京时间 (UTC+8) 转换
|
||||
|
||||
**常见错误** (错误码 1254064):
|
||||
|
||||
```json
|
||||
// ❌ 错误：使用 ISO 字符串
|
||||
{"截止日期": "2026-02-27"}
|
||||
|
||||
// ❌ 错误：使用 RFC3339 格式
|
||||
{"截止日期": "2026-02-27T10:00:00+08:00"}
|
||||
|
||||
// ❌ 错误：使用秒级时间戳
|
||||
{"截止日期": 1772121600} // 少了 3 位
|
||||
|
||||
// ✅ 正确：使用毫秒时间戳
|
||||
{"截止日期": 1772121600000}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 复选框 (type=7)
|
||||
|
||||
**写入/返回格式**: 布尔值
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"是否完成": true,
|
||||
"是否延期": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 人员 (type=11)
|
||||
|
||||
**写入格式**: 对象数组，**仅支持 `id` 字段**
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"负责人": [
|
||||
{"id": "ou_8240099442cf5da49f04f4bf8f8abcef"}
|
||||
],
|
||||
"协作人": [
|
||||
{"id": "ou_user1"},
|
||||
{"id": "ou_user2"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**: 对象数组，包含完整信息
|
||||
|
||||
```json
|
||||
{
|
||||
"负责人": [
|
||||
{
|
||||
"id": "ou_8240099442cf5da49f04f4bf8f8abcef",
|
||||
"name": "黄泡泡",
|
||||
"en_name": "Amanda Huang",
|
||||
"email": "amandahuang@xxxgmail.com",
|
||||
"avatar_url": "https://..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 重要**:
|
||||
- **写入时只支持 `id`**，不能传 `name`、`email` 等字段
|
||||
- `id` 类型需与 `user_id_type` 参数一致（open_id/union_id/user_id）
|
||||
- 单个单元格人员数不超过 1,000
|
||||
- 传空: `null` 或 `[]`
|
||||
|
||||
---
|
||||
|
||||
## 电话号码 (type=13)
|
||||
|
||||
**写入/返回格式**: 字符串
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"联系电话": "17899870000",
|
||||
"座机": "+86-010-12345678"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**格式规则**:
|
||||
- 符合正则: `(\+)?\d*`
|
||||
- 最大长度 64 字符
|
||||
|
||||
---
|
||||
|
||||
## 超链接 (type=15)
|
||||
|
||||
**写入/返回格式**: 对象
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"参考链接": {
|
||||
"text": "飞书开放平台",
|
||||
"link": "https://open.feishu.cn"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
- `text`: 显示的文本
|
||||
- `link`: URL 地址
|
||||
|
||||
**常见错误** (错误码 1254068):
|
||||
|
||||
```json
|
||||
// ❌ 错误：直接传字符串 URL
|
||||
{
|
||||
"参考链接": "https://open.feishu.cn"
|
||||
}
|
||||
|
||||
// ✅ 正确：使用对象格式
|
||||
{
|
||||
"参考链接": {
|
||||
"text": "飞书开放平台",
|
||||
"link": "https://open.feishu.cn"
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ text 和 link 可以相同
|
||||
{
|
||||
"参考链接": {
|
||||
"text": "https://open.feishu.cn",
|
||||
"link": "https://open.feishu.cn"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 附件 (type=17)
|
||||
|
||||
**写入格式**: 对象数组，**仅传 `file_token`**
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"附件": [
|
||||
{"file_token": "DRiFbwaKsoZaLax4WKZbEGCccoe"},
|
||||
{"file_token": "BZk3bL1Enoy4pzxaPL9bNeKqcLe"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**: 对象数组，包含完整信息
|
||||
|
||||
```json
|
||||
{
|
||||
"附件": [
|
||||
{
|
||||
"file_token": "J7GdbgNWWoD1fwx7oWccxdgknIe",
|
||||
"name": "58cc930b89.png",
|
||||
"type": "image/png",
|
||||
"size": 108867,
|
||||
"url": "https://open.feishu.cn/open-apis/drive/v1/medias/...",
|
||||
"tmp_url": "https://open.feishu.cn/open-apis/drive/v1/medias/batch_get_tmp_download_url?..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 重要**:
|
||||
- 写入前必须先调用[上传素材接口](https://go.feishu.cn/s/63soQp6O80s)获取 `file_token`
|
||||
- 单个单元格附件数不超过 100
|
||||
- 错误码 1254303: 附件未挂载到当前多维表格
|
||||
|
||||
---
|
||||
|
||||
## 单向关联 (type=18)
|
||||
|
||||
**写入格式**: `link_record_ids` 数组
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"关联任务": {
|
||||
"link_record_ids": ["recHTLvO7x", "recbS8zb2m"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**简化写入** (直接数组):
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"关联任务": ["recHTLvO7x", "recbS8zb2m"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**:
|
||||
|
||||
```json
|
||||
{
|
||||
"关联任务": {
|
||||
"link_record_ids": ["recHTLvO7x", "recbS8zb2m"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**限制**:
|
||||
- 单个单元格关联数不超过 500
|
||||
|
||||
---
|
||||
|
||||
## 双向关联 (type=21)
|
||||
|
||||
**写入/返回格式**: 与单向关联相同
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"相关项目": {
|
||||
"link_record_ids": ["reclzUoBLn", "rec7bYQoX1"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 更新双向关联会同步更新对方表的对应字段
|
||||
- 单个单元格关联数不超过 500
|
||||
|
||||
---
|
||||
|
||||
## 地理位置 (type=22)
|
||||
|
||||
**写入格式**: 经纬度字符串
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"办公地址": "116.397755,39.903179"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**: 对象，包含详细信息
|
||||
|
||||
```json
|
||||
{
|
||||
"办公地址": {
|
||||
"location": "116.352681,40.01437",
|
||||
"pname": "北京市",
|
||||
"cityname": "北京市",
|
||||
"adname": "海淀区",
|
||||
"address": "学清路10号院学清嘉创大厦",
|
||||
"name": "Bytedance",
|
||||
"full_address": "Bytedance，北京市北京市海淀区学清路10号院学清嘉创大厦"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
- `location`: 经纬度 (格式: "经度,纬度")
|
||||
- `pname`: 省
|
||||
- `cityname`: 市
|
||||
- `adname`: 区
|
||||
- `address`: 详细地址
|
||||
- `name`: 地名
|
||||
- `full_address`: 完整地址
|
||||
|
||||
---
|
||||
|
||||
## 群组 (type=23)
|
||||
|
||||
**写入格式**: 对象数组，**仅传 `id`**
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"协作群": [
|
||||
{"id": "oc_d2a947abb78bbbbb12d4cad55fbabcef"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**: 对象数组，包含完整信息
|
||||
|
||||
```json
|
||||
{
|
||||
"协作群": [
|
||||
{
|
||||
"id": "oc_d2a947abb78bbbbb12d4cad55fbabcef",
|
||||
"name": "测试部门",
|
||||
"avatar_url": "https://..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**限制**:
|
||||
- 单个单元格群组数不超过 10
|
||||
|
||||
---
|
||||
|
||||
## 公式/查找引用 (type=20, type=19)
|
||||
|
||||
**格式**: 对象，包含 `type`、`ui_type` 和 `value`
|
||||
|
||||
```json
|
||||
{
|
||||
"是否延期": {
|
||||
"type": 1, // 底层数据类型
|
||||
"ui_type": "Text", // UI 展示类型
|
||||
"value": [ // 计算结果
|
||||
{
|
||||
"text": "✅ 正常",
|
||||
"type": "text"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
- `type`: 底层数据类型枚举（1=文本, 2=数字, 5=日期...）
|
||||
- `ui_type`: UI 展示类型（"Text"/"Number"/"Progress"/...）
|
||||
- `value`: 计算结果，格式由 `type` 决定
|
||||
|
||||
**示例 - 数字类型公式**:
|
||||
|
||||
```json
|
||||
{
|
||||
"总价": {
|
||||
"type": 2,
|
||||
"ui_type": "Currency",
|
||||
"value": 1250.50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**示例 - 日期类型公式**:
|
||||
|
||||
```json
|
||||
{
|
||||
"计算日期": {
|
||||
"type": 5,
|
||||
"ui_type": "DateTime",
|
||||
"value": 1675526400000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 注意**:
|
||||
- 公式字段为**只读**，不能通过写接口设置
|
||||
- `value` 的数据结构取决于 `type` 对应的字段类型
|
||||
|
||||
---
|
||||
|
||||
## 系统字段
|
||||
|
||||
### 创建时间 (type=1001)
|
||||
|
||||
**返回格式**: Unix 毫秒时间戳
|
||||
|
||||
```json
|
||||
{
|
||||
"创建于": 1675526400000
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 只读**: 不能通过写接口设置
|
||||
|
||||
---
|
||||
|
||||
### 最后更新时间 (type=1002)
|
||||
|
||||
**返回格式**: Unix 毫秒时间戳
|
||||
|
||||
```json
|
||||
{
|
||||
"更新于": 1675612800000
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 只读**: 不能通过写接口设置
|
||||
|
||||
---
|
||||
|
||||
### 创建人 / 修改人 (type=1003, type=1004)
|
||||
|
||||
**返回格式**: 对象数组（与人员字段相同）
|
||||
|
||||
```json
|
||||
{
|
||||
"创建人": [
|
||||
{
|
||||
"id": "ou_8240099442cf5da49f04f4bf8f8abcef",
|
||||
"name": "黄泡泡",
|
||||
"en_name": "Amanda Huang",
|
||||
"email": "amandahuang@xxxgmail.com",
|
||||
"avatar_url": "https://..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 只读**: 不能通过写接口设置
|
||||
|
||||
---
|
||||
|
||||
### 自动编号 (type=1005)
|
||||
|
||||
**返回格式**: 字符串
|
||||
|
||||
```json
|
||||
{
|
||||
"工单号": "WO-20240226-0001"
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 只读**: 不能通过写接口设置
|
||||
|
||||
---
|
||||
|
||||
## 🔍 常见错误与排查
|
||||
|
||||
### 字段类型不匹配 (错误码 1254015)
|
||||
|
||||
**错误示例**:
|
||||
|
||||
```json
|
||||
// ❌ 错误: 日期字段传字符串
|
||||
{
|
||||
"fields": {
|
||||
"截止日期": "2024-02-26" // 应该传时间戳
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
{
|
||||
"fields": {
|
||||
"截止日期": 1708905600000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 人员字段格式错误 (错误码 1254066)
|
||||
|
||||
**常见原因**:
|
||||
|
||||
1. **传入了不支持的字段**:
|
||||
|
||||
```json
|
||||
// ❌ 错误
|
||||
{
|
||||
"负责人": [
|
||||
{"name": "张三"} // 只能传 id
|
||||
]
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
{
|
||||
"负责人": [
|
||||
{"id": "ou_xxx"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
2. **user_id_type 不匹配**:
|
||||
|
||||
```bash
|
||||
# 请求时指定了 user_id_type=open_id，但传的是 union_id
|
||||
```
|
||||
|
||||
3. **跨应用传 open_id**:
|
||||
|
||||
```
|
||||
不同应用的 open_id 不能交叉使用，建议使用 user_id
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 附件未挂载 (错误码 1254303)
|
||||
|
||||
**原因**: 直接传入外部 file_token
|
||||
|
||||
**解决**:
|
||||
|
||||
1. 先调用[上传素材接口](https://go.feishu.cn/s/63soQp6O80s)上传到当前多维表格
|
||||
2. 使用返回的 `file_token` 写入记录
|
||||
|
||||
---
|
||||
|
||||
### 字段名不存在 (错误码 1254045)
|
||||
|
||||
**原因**: 字段名称不完全匹配（可能有空格、换行、特殊字符）
|
||||
|
||||
**排查**:
|
||||
|
||||
1. 调用[列出字段接口](https://go.feishu.cn/s/62nuKkQlk03)获取准确字段名
|
||||
2. 检查首尾空格、换行符
|
||||
|
||||
---
|
||||
|
||||
### 超链接字段转换失败 (错误码 1254068)
|
||||
|
||||
**原因**: 缺少 `text` 或 `link` 字段
|
||||
|
||||
```json
|
||||
// ❌ 错误
|
||||
{
|
||||
"参考链接": {
|
||||
"link": "https://example.com" // 缺少 text
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
{
|
||||
"参考链接": {
|
||||
"text": "示例网站",
|
||||
"link": "https://example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📌 最佳实践
|
||||
|
||||
### 1. 批量写入优化
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"任务名称": "拜访客户",
|
||||
"负责人": [{"id": "ou_xxx"}],
|
||||
"截止日期": 1708905600000,
|
||||
"标签": ["重要", "紧急"],
|
||||
"是否完成": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**建议**:
|
||||
- 一次性传入所有字段，避免多次调用
|
||||
- 只传需要设置的字段，不必包含所有列
|
||||
|
||||
---
|
||||
|
||||
### 2. 清空字段值
|
||||
|
||||
**方法 1**: 传 `null`
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"负责人": null,
|
||||
"标签": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**方法 2**: 传空数组/空字符串（根据字段类型）
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"负责人": [],
|
||||
"任务名称": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 时间戳转换
|
||||
|
||||
**JavaScript**:
|
||||
|
||||
```javascript
|
||||
// 北京时间字符串 → Unix 毫秒时间戳
|
||||
const timestamp = new Date("2024-02-26 14:00").getTime() // 1708927200000
|
||||
|
||||
// Unix 毫秒时间戳 → 日期字符串
|
||||
const date = new Date(1708927200000).toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' })
|
||||
```
|
||||
|
||||
**Python**:
|
||||
|
||||
```python
|
||||
import datetime
|
||||
|
||||
# 北京时间字符串 → Unix 毫秒时间戳
|
||||
dt = datetime.datetime(2024, 2, 26, 14, 0, 0)
|
||||
timestamp = int(dt.timestamp() * 1000) # 1708927200000
|
||||
|
||||
# Unix 毫秒时间戳 → 日期字符串
|
||||
dt = datetime.datetime.fromtimestamp(1708927200000 / 1000)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 关联字段的级联更新
|
||||
|
||||
**双向关联**:
|
||||
|
||||
```json
|
||||
// 更新 Table A 的双向关联字段
|
||||
{
|
||||
"fields": {
|
||||
"关联项目": {
|
||||
"link_record_ids": ["rec123"]
|
||||
}
|
||||
}
|
||||
}
|
||||
// Table B 的对应双向关联字段会自动更新
|
||||
```
|
||||
|
||||
**单向关联**:
|
||||
|
||||
```json
|
||||
// 只更新当前表，不影响关联表
|
||||
{
|
||||
"fields": {
|
||||
"参考任务": {
|
||||
"link_record_ids": ["rec456"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 参考链接
|
||||
|
||||
- [飞书开放平台 - 多维表格记录数据结构](https://go.feishu.cn/s/6lY28723w04)
|
||||
- [新增记录接口文档](https://go.feishu.cn/s/61Y-IrQjU02)
|
||||
- [更新记录接口文档](https://go.feishu.cn/s/6lY28723A04)
|
||||
- [上传素材接口](https://go.feishu.cn/s/63soQp6O80s)
|
||||
Reference in New Issue
Block a user