yangxuan/openclaw-config

Fork 0

Files

T

openclaw-314 0aa13d3cf0 auto: sync OpenClaw config 2026-09-09 16:13

2026-09-09 16:13:31 +08:00

15 KiB

Raw Blame History

飞书多维表格记录值数据结构详解

本文档详细说明每种字段类型在记录中对应的 fields 值格式。

来源: 基于飞书开放平台文档多维表格记录数据结构

📋 快速索引

字段类型	type	值类型	示例	限制
文本	1	string (写入) / list of object (返回)	`"任务描述"`	最多 10 万字符
数字	2	number	`0.5`	-
单选	3	string	`"进行中"`	选项总数≤20,000
多选	4	array<string>	`["审批", "办公"]`	选项总数≤20,000，单元格≤1,000
日期	5	number	`1675526400000`	Unix 毫秒时间戳
复选框	7	boolean	`true`	-
人员	11	list of object	`[{"id": "ou_xxx"}]`	单元格≤1,000，写入仅支持 `id`
电话	13	string	`"17899870000"`	最多 64 字符
超链接	15	object	`{"text": "飞书", "link": "..."}`	-
附件	17	list of object	`[{"file_token": "xxx"}]`	单元格≤100
单向关联	18	object	`{"link_record_ids": [...]}`	单元格≤500
双向关联	21	object	`{"link_record_ids": [...]}`	单元格≤500
地理位置	22	object	`{"location": "116.3,40.0", ...}`	-
群组	23	list of object	`[{"id": "oc_xxx"}]`	单元格≤10
公式/查找引用	20/19	object	`{"type": 1, "value": [...]}`	只读

文本 (type=1)

基础文本 (ui_type="Text")

写入格式: 字符串

{
  "fields": {
    "任务描述": "维护客户关系"
  }
}

返回格式: 对象数组

{
  "任务描述": [
    {
      "text": "维护客户关系",
      "type": "text"
    }
  ]
}

富文本格式 (提及人、超链接):

{
  "任务描述": [
    {
      "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")

写入格式: 字符串

{
  "fields": {
    "商品条码": "FS0001"
  }
}

返回格式:

{
  "商品条码": [
    {
      "text": "FS0001",
      "type": "text"
    }
  ]
}

邮箱 (ui_type="Email")

写入格式: 字符串

{
  "fields": {
    "联系邮箱": "zhangmin@xxxgmail.com"
  }
}

返回格式:

{
  "联系邮箱": [
    {
      "text": "zhangmin@xxxgmail.com",
      "type": "url",
      "link": "mailto:zhangmin@xxxgmail.com"
    }
  ]
}

数字 (type=2)

写入/返回格式: 数字

{
  "fields": {
    "工时": 10,
    "完成率": 0.75,
    "预算": 5000.50
  }
}

注意:

进度 (ui_type="Progress"): 0-1 范围的小数
货币 (ui_type="Currency"): 普通数字
评分 (ui_type="Rating"): 整数

单选 (type=3)

写入格式: 选项名称字符串

{
  "fields": {
    "任务状态": "进行中"
  }
}

新选项: 传入不存在的选项名会自动创建新选项

{
  "fields": {
    "任务状态": "已暂停"  // 如果不存在，会自动创建
  }
}

返回格式: 与写入相同

{
  "任务状态": "进行中"
}

限制:

选项总数不超过 20,000

多选 (type=4)

写入格式: 字符串数组

{
  "fields": {
    "标签": ["审批集成", "办公管理", "身份管理"]
  }
}

新选项: 传入不存在的选项名会自动创建新选项

{
  "fields": {
    "标签": ["新标签1", "新标签2"]  // 不存在的会自动创建
  }
}

返回格式: 与写入相同

{
  "标签": ["审批集成", "办公管理"]
}

限制:

选项总数不超过 20,000
单个单元格选项数不超过 1,000

日期 (type=5)

写入/返回格式: Unix 毫秒时间戳

{
  "fields": {
    "截止日期": 1675526400000  // 2023-02-05 00:00:00 (UTC)
  }
}

注意:

必须使用毫秒级时间戳（不是秒级）
建议使用北京时间 (UTC+8) 转换

常见错误 (错误码 1254064):

// ❌ 错误：使用 ISO 字符串
{"截止日期": "2026-02-27"}

// ❌ 错误：使用 RFC3339 格式
{"截止日期": "2026-02-27T10:00:00+08:00"}

// ❌ 错误：使用秒级时间戳
{"截止日期": 1772121600}  // 少了 3 位

// ✅ 正确：使用毫秒时间戳
{"截止日期": 1772121600000}

复选框 (type=7)

写入/返回格式: 布尔值

{
  "fields": {
    "是否完成": true,
    "是否延期": false
  }
}

人员 (type=11)

写入格式: 对象数组，仅支持 id 字段

{
  "fields": {
    "负责人": [
      {"id": "ou_8240099442cf5da49f04f4bf8f8abcef"}
    ],
    "协作人": [
      {"id": "ou_user1"},
      {"id": "ou_user2"}
    ]
  }
}

返回格式: 对象数组，包含完整信息

{
  "负责人": [
    {
      "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)

写入/返回格式: 字符串

{
  "fields": {
    "联系电话": "17899870000",
    "座机": "+86-010-12345678"
  }
}

格式规则:

符合正则: (\+)?\d*
最大长度 64 字符

超链接 (type=15)

写入/返回格式: 对象

{
  "fields": {
    "参考链接": {
      "text": "飞书开放平台",
      "link": "https://open.feishu.cn"
    }
  }
}

字段说明:

text: 显示的文本
link: URL 地址

常见错误 (错误码 1254068):

// ❌ 错误：直接传字符串 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

{
  "fields": {
    "附件": [
      {"file_token": "DRiFbwaKsoZaLax4WKZbEGCccoe"},
      {"file_token": "BZk3bL1Enoy4pzxaPL9bNeKqcLe"}
    ]
  }
}

返回格式: 对象数组，包含完整信息

{
  "附件": [
    {
      "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?..."
    }
  ]
}

⚠️ 重要:

写入前必须先调用上传素材接口获取 file_token
单个单元格附件数不超过 100
错误码 1254303: 附件未挂载到当前多维表格

单向关联 (type=18)

写入格式: link_record_ids 数组

{
  "fields": {
    "关联任务": {
      "link_record_ids": ["recHTLvO7x", "recbS8zb2m"]
    }
  }
}

简化写入 (直接数组):

{
  "fields": {
    "关联任务": ["recHTLvO7x", "recbS8zb2m"]
  }
}

返回格式:

{
  "关联任务": {
    "link_record_ids": ["recHTLvO7x", "recbS8zb2m"]
  }
}

限制:

单个单元格关联数不超过 500

双向关联 (type=21)

写入/返回格式: 与单向关联相同

{
  "fields": {
    "相关项目": {
      "link_record_ids": ["reclzUoBLn", "rec7bYQoX1"]
    }
  }
}

注意:

更新双向关联会同步更新对方表的对应字段
单个单元格关联数不超过 500

地理位置 (type=22)

写入格式: 经纬度字符串

{
  "fields": {
    "办公地址": "116.397755,39.903179"
  }
}

返回格式: 对象，包含详细信息

{
  "办公地址": {
    "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

{
  "fields": {
    "协作群": [
      {"id": "oc_d2a947abb78bbbbb12d4cad55fbabcef"}
    ]
  }
}

返回格式: 对象数组，包含完整信息

{
  "协作群": [
    {
      "id": "oc_d2a947abb78bbbbb12d4cad55fbabcef",
      "name": "测试部门",
      "avatar_url": "https://..."
    }
  ]
}

限制:

单个单元格群组数不超过 10

公式/查找引用 (type=20, type=19)

格式: 对象，包含 type、ui_type 和 value

{
  "是否延期": {
    "type": 1,                    // 底层数据类型
    "ui_type": "Text",            // UI 展示类型
    "value": [                    // 计算结果
      {
        "text": "✅ 正常",
        "type": "text"
      }
    ]
  }
}

字段说明:

type: 底层数据类型枚举（1=文本, 2=数字, 5=日期...）
ui_type: UI 展示类型（"Text"/"Number"/"Progress"/...）
value: 计算结果，格式由 type 决定

示例 - 数字类型公式:

{
  "总价": {
    "type": 2,
    "ui_type": "Currency",
    "value": 1250.50
  }
}

示例 - 日期类型公式:

{
  "计算日期": {
    "type": 5,
    "ui_type": "DateTime",
    "value": 1675526400000
  }
}

⚠️ 注意:

公式字段为只读，不能通过写接口设置
value 的数据结构取决于 type 对应的字段类型

系统字段

创建时间 (type=1001)

返回格式: Unix 毫秒时间戳

{
  "创建于": 1675526400000
}

⚠️ 只读: 不能通过写接口设置

最后更新时间 (type=1002)

返回格式: Unix 毫秒时间戳

{
  "更新于": 1675612800000
}

⚠️ 只读: 不能通过写接口设置

创建人 / 修改人 (type=1003, type=1004)

返回格式: 对象数组（与人员字段相同）

{
  "创建人": [
    {
      "id": "ou_8240099442cf5da49f04f4bf8f8abcef",
      "name": "黄泡泡",
      "en_name": "Amanda Huang",
      "email": "amandahuang@xxxgmail.com",
      "avatar_url": "https://..."
    }
  ]
}

⚠️ 只读: 不能通过写接口设置

自动编号 (type=1005)

返回格式: 字符串

{
  "工单号": "WO-20240226-0001"
}

⚠️ 只读: 不能通过写接口设置

🔍 常见错误与排查

字段类型不匹配 (错误码 1254015)

错误示例:

// ❌ 错误: 日期字段传字符串
{
  "fields": {
    "截止日期": "2024-02-26"  // 应该传时间戳
  }
}

// ✅ 正确
{
  "fields": {
    "截止日期": 1708905600000
  }
}

人员字段格式错误 (错误码 1254066)

常见原因:

传入了不支持的字段:

// ❌ 错误
{
  "负责人": [
    {"name": "张三"}  // 只能传 id
  ]
}

// ✅ 正确
{
  "负责人": [
    {"id": "ou_xxx"}
  ]
}

user_id_type 不匹配:

# 请求时指定了 user_id_type=open_id，但传的是 union_id

跨应用传 open_id:

不同应用的 open_id 不能交叉使用，建议使用 user_id

附件未挂载 (错误码 1254303)

原因: 直接传入外部 file_token

解决:

先调用上传素材接口上传到当前多维表格
使用返回的 file_token 写入记录

字段名不存在 (错误码 1254045)

原因: 字段名称不完全匹配（可能有空格、换行、特殊字符）

排查:

调用列出字段接口获取准确字段名
检查首尾空格、换行符

超链接字段转换失败 (错误码 1254068)

原因: 缺少 text 或 link 字段

// ❌ 错误
{
  "参考链接": {
    "link": "https://example.com"  // 缺少 text
  }
}

// ✅ 正确
{
  "参考链接": {
    "text": "示例网站",
    "link": "https://example.com"
  }
}

📌 最佳实践

1. 批量写入优化

{
  "fields": {
    "任务名称": "拜访客户",
    "负责人": [{"id": "ou_xxx"}],
    "截止日期": 1708905600000,
    "标签": ["重要", "紧急"],
    "是否完成": false
  }
}

建议:

一次性传入所有字段，避免多次调用
只传需要设置的字段，不必包含所有列

2. 清空字段值

方法 1: 传 null

{
  "fields": {
    "负责人": null,
    "标签": null
  }
}

方法 2: 传空数组/空字符串（根据字段类型）

{
  "fields": {
    "负责人": [],
    "任务名称": ""
  }
}

3. 时间戳转换

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:

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. 关联字段的级联更新

双向关联:

// 更新 Table A 的双向关联字段
{
  "fields": {
    "关联项目": {
      "link_record_ids": ["rec123"]
    }
  }
}
// Table B 的对应双向关联字段会自动更新

单向关联:

// 只更新当前表，不影响关联表
{
  "fields": {
    "参考任务": {
      "link_record_ids": ["rec456"]
    }
  }
}

15 KiB Raw Blame History Unescape Escape

飞书多维表格记录值数据结构详解

📋 快速索引

文本 (type=1)

基础文本 (ui_type="Text")

条码 (ui_type="Barcode")

邮箱 (ui_type="Email")

数字 (type=2)

单选 (type=3)

多选 (type=4)

日期 (type=5)

复选框 (type=7)

人员 (type=11)

电话号码 (type=13)

超链接 (type=15)

附件 (type=17)

单向关联 (type=18)

双向关联 (type=21)

地理位置 (type=22)

群组 (type=23)

公式/查找引用 (type=20, type=19)

系统字段

创建时间 (type=1001)

最后更新时间 (type=1002)

创建人 / 修改人 (type=1003, type=1004)

自动编号 (type=1005)

🔍 常见错误与排查

字段类型不匹配 (错误码 1254015)

人员字段格式错误 (错误码 1254066)

附件未挂载 (错误码 1254303)

字段名不存在 (错误码 1254045)

超链接字段转换失败 (错误码 1254068)

📌 最佳实践

1. 批量写入优化

2. 清空字段值

3. 时间戳转换

4. 关联字段的级联更新

🔗 参考链接

15 KiB

Raw Blame History