14 KiB
14 KiB
飞书多维表格字段 Property 配置详解
本文档详细说明每种字段类型创建或更新时需要的 property 参数结构。
来源: 基于飞书开放平台文档 字段编辑指南
📋 目录
基础字段
1. 文本 (type=1)
Property 结构: 空对象或省略
{
"type": 1,
"field_name": "任务描述",
"property": {}
}
注意:
- 默认
ui_type为 "Text" - 单个单元格最多 10 万字符
- 支持富文本格式（提及人、超链接等）
2. 数字 (type=2)
Property 结构:
{
"formatter": "0" // 可选，数字显示格式
}
formatter 可选值:
"0": 整数（默认）"0.0": 一位小数"0.00": 两位小数"0,000": 千分位"0.00%": 百分比
示例:
{
"type": 2,
"field_name": "工时",
"property": {
"formatter": "0.00"
}
}
5. 日期 (type=5)
Property 结构:
{
"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
示例:
{
"type": 5,
"field_name": "截止日期",
"property": {
"date_formatter": "yyyy-MM-dd HH:mm",
"auto_fill": false
}
}
7. 复选框 (type=7)
Property 结构: 空对象或省略
{
"type": 7,
"field_name": "是否完成",
"property": {}
}
13. 电话号码 (type=13)
Property 结构: 空对象或省略
{
"type": 13,
"field_name": "联系电话",
"property": {}
}
注意:
- 电话号码格式：符合正则
(\+)?\d* - 最大长度 64 字符
选择字段
3. 单选 (type=3)
Property 结构:
{
"options": [
{
"name": "进行中", // 必填，选项名称
"color": 0 // 可选，颜色编号 (0-54)
},
{
"name": "已完成",
"color": 10
}
]
}
颜色编号 (color):
- 范围: 0-54
- 0: 红色
- 10: 绿色
- 20: 蓝色
- ... (详见飞书官方文档)
示例:
{
"type": 3,
"field_name": "任务状态",
"property": {
"options": [
{"name": "待开始", "color": 0},
{"name": "进行中", "color": 20},
{"name": "已完成", "color": 10}
]
}
}
注意:
- 选项总数不超过 20,000 个
- 创建时不能指定选项 ID（
id字段），系统自动生成 - 更新时需保留已有选项的
id
4. 多选 (type=4)
Property 结构: 与单选相同
{
"options": [
{"name": "紧急", "color": 0},
{"name": "重要", "color": 10}
]
}
注意:
- 选项总数不超过 20,000 个
- 单个单元格选项数不超过 1,000 个
特殊显示字段
进度 (type=2, ui_type="Progress")
Property 结构:
{
"min": 0, // 必填，最小值
"max": 100, // 必填，最大值
"range_customize": false // 可选，是否允许自定义进度值
}
示例:
{
"type": 2,
"field_name": "完成进度",
"ui_type": "Progress",
"property": {
"min": 0,
"max": 100,
"range_customize": true
}
}
注意:
min取值范围: 0-1max取值范围: 1-100range_customize为true时用户可输入超出范围的值
货币 (type=2, ui_type="Currency")
Property 结构:
{
"currency_code": "CNY", // 必填，货币类型
"formatter": "0.00" // 可选，数字格式
}
currency_code 可选值:
"CNY": 人民币 (¥)"USD": 美元 ($)"EUR": 欧元 (€)"GBP": 英镑 (£)"JPY": 日元 (¥)"HKD": 港元 ($)- ... (支持 20+ 种货币)
示例:
{
"type": 2,
"field_name": "预算",
"ui_type": "Currency",
"property": {
"currency_code": "USD",
"formatter": "0,000.00"
}
}
评分 (type=2, ui_type="Rating")
Property 结构:
{
"min": 1, // 必填，最小值
"max": 5, // 必填，最大值
"rating": { // 可选，评分样式
"symbol": "star" // 图标类型
}
}
symbol 可选值:
"star": ⭐ 星星（默认）"heart": ❤️ 爱心"thumbsup": 👍 赞"fire": 🔥 火焰"smile": 😊 笑脸"lightning": ⚡ 闪电"flower": 🌸 花朵"number": 数字
示例:
{
"type": 2,
"field_name": "优先级",
"ui_type": "Rating",
"property": {
"min": 1,
"max": 5,
"rating": {
"symbol": "fire"
}
}
}
条码 (type=1, ui_type="Barcode")
Property 结构:
{
"allowed_edit_modes": {
"manual": true, // 是否允许手动录入
"scan": true // 是否允许扫描录入
}
}
示例:
{
"type": 1,
"field_name": "商品条码",
"ui_type": "Barcode",
"property": {
"allowed_edit_modes": {
"manual": false,
"scan": true
}
}
}
邮箱 (type=1, ui_type="Email")
Property 结构: 空对象或省略
{
"type": 1,
"field_name": "联系邮箱",
"ui_type": "Email",
"property": {}
}
关系字段
11. 人员 (type=11)
Property 结构:
{
"multiple": true // 可选，是否允许多个人员，默认 true
}
示例:
{
"type": 11,
"field_name": "负责人",
"property": {
"multiple": false // 只允许单个人员
}
}
注意:
- 单个单元格人员数不超过 1,000
- 记录值只支持传入
id字段（open_id/union_id/user_id）
15. 超链接 (type=15)
Property 结构: 必须省略 property 参数，不要传递任何值（包括空对象）
{
"type": 15,
"field_name": "参考链接"
// 不要传 property 参数，包括空对象 {}
}
⚠️ 重要: 超链接字段的特殊要求（经实测验证）：
- ✅ 正确: 完全省略
property参数 - ❌ 错误:
"property": {}（会报 URLFieldPropertyError） - ❌ 错误: 传递任何 property 值
注意: 这是飞书 API 的特殊行为，超链接字段即使传空对象也会报错，必须完全省略该参数。
17. 附件 (type=17)
Property 结构: 空对象或省略
{
"type": 17,
"field_name": "附件",
"property": {}
}
注意:
- 单个单元格附件数不超过 100
- 写入前需先调用上传素材接口
18. 单向关联 (type=18)
Property 结构:
{
"table_id": "tblXXXXXXXX", // 必填，关联的数据表 ID
"multiple": true // 可选，是否允许多条记录，默认 true
}
示例:
{
"type": 18,
"field_name": "关联任务",
"property": {
"table_id": "tblsRc9GRRXKqhvW",
"multiple": true
}
}
注意:
- 单个单元格关联数不超过 500
21. 双向关联 (type=21)
Property 结构:
{
"table_id": "tblXXXXXXXX", // 必填，关联的数据表 ID
"back_field_name": "反向字段名", // 必填，对方表的双向关联字段名
"multiple": true // 可选，是否允许多条记录
}
示例:
{
"type": 21,
"field_name": "相关项目",
"property": {
"table_id": "tblAnotherTable",
"back_field_name": "关联的任务",
"multiple": true
}
}
注意:
- 单个单元格关联数不超过 500
- 对方表会自动创建对应的双向关联字段
22. 地理位置 (type=22)
Property 结构:
{
"location": {
"input_type": "not_limit" // 输入限制
}
}
input_type 可选值:
"only_mobile": 仅允许移动端实时定位"not_limit": 无限制（默认）
示例:
{
"type": 22,
"field_name": "办公地址",
"property": {
"location": {
"input_type": "only_mobile"
}
}
}
23. 群组 (type=23)
Property 结构: 空对象或省略
{
"type": 23,
"field_name": "协作群",
"property": {}
}
注意:
- 单个单元格群组数不超过 10 个
高级字段
20. 公式 (type=20)
Property 结构:
{
"formula_expression": "bitable::$table[tblXXX].$field[fldYYY]*2" // 可选
}
示例:
{
"type": 20,
"field_name": "总价",
"property": {
"formula_expression": "bitable::$table[tblMain].$field[fldQty] * $field[fldPrice]"
}
}
注意:
- 创建字段时不支持设置公式表达式
- 参考飞书帮助中心 - 公式字段
对于某些多维表格，公式字段需要额外设置 type 参数（通过获取多维表格元数据接口的 formula_type 判断）:
{
"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 结构:
{
"date_formatter": "yyyy/MM/dd" // 可选，日期格式
}
示例:
{
"type": 1001,
"field_name": "创建于",
"property": {
"date_formatter": "yyyy-MM-dd HH:mm"
}
}
1002. 最后更新时间 (type=1002)
Property 结构: 与创建时间相同
{
"date_formatter": "yyyy-MM-dd HH:mm"
}
1005. 自动编号 (type=1005)
Property 结构:
{
"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: 纯自增:
{
"type": 1005,
"field_name": "编号",
"property": {
"auto_serial": {
"type": "auto_increment_number"
}
}
}
示例 2: 自定义编号:
{
"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 更新字段时：
- 必须保持字段类型一致:
type和ui_type不能变更 - 单选/多选更新选项:
- 已有选项必须保留
id - 新增选项只传
name和color，不传id
- 已有选项必须保留
- 如果只改字段名:
- 可以只传
field_name，工具会自动查询当前type和property
- 可以只传
- 关联字段的 table_id: 不能修改为不同的表