764 lines
14 KiB
Markdown
764 lines
14 KiB
Markdown
# 飞书多维表格字段 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)
|