字段编辑指南

字段概述

字段是一个object结构类型。结构如下：

名称	类型	描述
field_id	string	字段id
field_name	string	字段名
type	int	字段类型： 1：多行文本 2：数字 3：单选 4：多选 5：日期 7：复选框 11：人员 13：电话号码 15：超链接 17：附件 18：单向关联 19：查找引用 20：公式 21：双向关联 22：地理位置 1001：创建时间 1002：最后更新时间 1003：创建人 1004：修改人 1005：自动编号
property	object	字段属性，因字段类型而异

注意：

更新字段时为全量更新，property会被完全覆盖。在下面的单选、多选字段的更新字段的请求体示例中有所体现。

Property说明

部分类型字段有特殊的属性配置，在下面列出。其他类型字段的property均为null。

数字字段

Property结构

名称	类型	描述	必填	是否是枚举值	可选枚举值	默认值
formatter	string	格式，参考：formatter	否	是	参考：formatter	"0.0"

网页中数字格式与formatter的对应关系

网页中数字格式	formatter
整数	"0"
保留1位小数	"0.0"
保留2位小数	"0.00"
保留3位小数	"0.000"
保留4位小数	"0.0000"
千分位	"1,000"
千分位（小数点）	"1,000.00"
百分比	"%"
百分比（小数点）	"0.00%"
人民币	"¥"
人民币（小数点）	"¥0.00"
美元	"$"
美元（小数点）	"$0.00"

新增、更新字段的请求体示例

{
    "field_name": "数字",
    "type": 2,
    "property": {
        "formatter": "0.00"
    }
}

响应体示例

{
    "code": 0,
    "data": {
        "field": {
            "field_id": "fldoMnnvIR",
            "field_name": "数字",
            "property": {
                "formatter": "0.00"
            },
            "type": 2
        }
    },
    "msg": "Success"
}

单选、多选字段

Property结构

名称	类型	描述	必填	是否是枚举值	可选枚举值	默认值
options	app.table.field.property.option[]	选项列表	否	否	-	-
∟id	string	选项id	否	否	-	-
∟name	string	选项名	否	否	-	-
∟color	int	选项颜色	否	是	0~54	从上一个选项的color开始依次递增

新增字段的请求体示例

{
    "field_name": "单选",
    "type": 3,
    "property": {
        "options": [
            {
                "name": "a"
            },
            {
                "name": "b"
            },
            {
                "name": "c",
                "color": 5
            },
            {
                "name": "d"
            }
        ]
    }
}

响应体示例

{
    "code": 0,
    "data": {
        "field": {
            "field_id": "fld2RxOyB8",
            "field_name": "单选",
            "property": {
                "options": [
                    {
                        "color": 0,
                        "id": "optpeuQVqp",
                        "name": "a"
                    },
                    {
                        "color": 1,
                        "id": "opt5g3xLFT",
                        "name": "b"
                    },
                    {
                        "color": 5,
                        "id": "optDIEs1h0",
                        "name": "c"
                    },
                    {
                        "color": 6,
                        "id": "optZZceUac",
                        "name": "d"
                    }
                ]
            },
            "type": 3
        }
    },
    "msg": "Success"
}

更新字段的请求体示例

现在，我想更新选项a的name为a++，选项b保持不变，删除选项c和选项d，新增选项z，请求体如下：

{
    "field_name": "单选",
    "type": 3,
    "property": {
        "options": [
            {
                "color": 0,
                "id": "optpeuQVqp", // 若携带id，id必须是旧的单选、多选字段property中已存在的选项id
                "name": "a++"
            },
            {
                "color": 1,
                "id": "opt5g3xLFT",
                "name": "b"
            },
            {
                "color": 6,
                "name": "z" // 不携带id，新增一个选项
            }
        ]
    }
}

响应体示例

因为更新字段是全量更新，选项c和选项d已删除，响应体如下：

{
    "code": 0,
    "data": {
        "field": {
            "field_id": "fld2RxOyB8",
            "field_name": "单选",
            "property": {
                "options": [
                    {
                        "color": 0,
                        "id": "optpeuQVqp",
                        "name": "a++"
                    },
                    {
                        "color": 1,
                        "id": "opt5g3xLFT",
                        "name": "b"
                    },
                    {
                        "color": 6,
                        "id": "opt558YmTi",
                        "name": "z"
                    }
                ]
            },
            "type": 3
        }
    },
    "msg": "Success"
}

日期字段

Property结构

名称	类型	描述	必填	是否是枚举值	可选枚举值	默认值
date_formatter	string	日期格式，参考：日期格式date_formatter	否	是	参考：日期格式date_formatter	"yyyy/MM/dd"
auto_fill	boolean	新纪录自动填写创建时间	否	否	-	false

网页中日期格式与date_formatter的对应关系

网页中日期格式	date_formatter
2021/01/30	"yyyy/MM/dd"
2021/01/30 14:00	"yyyy/MM/dd HH:mm"
2021-01-30	"yyyy-MM-dd"
2021-01-30 14:00	"yyyy-MM-dd HH:mm"
01-30	"MM-dd"
01/30/2021	"MM/dd/yyyy"
30/01/2021	"dd/MM/yyyy"

新增、更新字段的请求体示例

{
    "field_name": "日期",
    "type": 5,
    "property": {
        "date_formatter": "yyyy/MM/dd HH:mm",
        "auto_fill": false
    }
}

响应体示例

{
    "code": 0,
    "data": {
        "field": {
            "field_id": "fldHBDkAfH",
            "field_name": "日期",
            "property": {
                "auto_fill": false,
                "date_formatter": "yyyy/MM/dd HH:mm"
            },
            "type": 5
        }
    },
    "msg": "Success"
}

人员字段

Property结构

名称	类型	描述	必填	是否是枚举值	可选枚举值	默认值
multiple	boolean	允许添加多个成员	否	否	-	true

新增、更新字段的请求体示例

{
    "field_name": "人员",
    "type": 11,
    "property": {
        "multiple": true
    }
}

响应体示例

{
    "code": 0,
    "data": {
        "field": {
            "field_id": "fldlQDzjyK",
            "field_name": "人员",
            "property": {
                "multiple": true
            },
            "type": 11
        }
    },
    "msg": "Success"
}

单向关联字段

Property结构

名称	类型	描述	必填	是否是枚举值	可选枚举值	默认值
multiple	boolean	允许添加多个记录	否	否	-	true
table_id	string	关联的数据表的id	是	否	-	-
table_name	string	关联的数据表的名字（仅在响应体中返回）	-	-	-	-

新增、更新字段的请求体示例

{
    "field_name": "单向关联",
    "type": 18,
    "property": {
        "multiple": true,
        "table_id": "tblw92ErelmCmgHc"
    }
}

响应体示例

{
    "code": 0,
    "data": {
        "field": {
            "field_id": "fldNdr8VNW",
            "field_name": "单向关联",
            "property": {
                "multiple": true,
                "table_id": "tblw92ErelmCmgHc",
                "table_name": "数据表2"
            },
            "type": 18
        }
    },
    "msg": "Success"
}

双向关联字段

Property结构

名称	类型	描述	必填	是否是枚举值	可选枚举值	默认值
back_field_id	string	关联的数据表中双向关联字段的id（仅在响应体中返回）	-	-	-	-
back_field_name	string	关联的数据表中双向关联字段的名字	否	否	-	关联的数据表名-本字段名
multiple	boolean	允许添加多个记录	否	否	-	true
table_id	string	关联的数据表的id	是	否	-	-
table_name	String	关联的数据表的名字（仅在响应体中返回）	-	-	-	-

新增、更新字段的请求体示例

{
    "field_name": "双向关联",
    "type": 21,
    "property": {
        "multiple": true,
        "table_id": "tblw92ErelmCmgHc",
        "back_field_name": "双向关联-自动生成"
    }
}

响应体示例

{
    "code": 0,
    "data": {
        "field": {
            "field_id": "fldpfIDIi0",
            "field_name": "双向关联",
            "property": {
                "back_field_id": "fldmQGUnWh",
                "back_field_name": "双向关联-自动生成",
                "multiple": true,
                "table_id": "tblw92ErelmCmgHc",
                "table_name": "数据表2"
            },
            "type": 21
        }
    },
    "msg": "Success"
}

公式字段

Property结构

名称	类型	描述	必填	是否是枚举值	可选枚举值	默认值
formatter	string	格式参考：formatter	否	是	参考：formatter	""
formula_expression	string	格式参考：formula	否	否		""

网页中公式格式与formatter的对应关系

网页中公式格式	formatter
默认	""
整数	"0"
保留1位小数	"0.0"
保留2位小数	"0.00"
千分位	"1,000"
千分位（小数点）	"1,000.00"
百分比	"%"
百分比（小数点）	"0.00%"
人民币	"¥"
人民币（小数点）	"¥0.00"
美元	"$"
美元（小数点）	"$0.00"
2021/01/30 14:00	"yyyy/MM/dd HH:mm"
2021/01/30	"yyyy/MM/dd"
2021-01-30	"yyyy-MM-dd"
01-30	"MM-dd"

新增、更新字段的请求体示例

{
    "field_name": "公式",
    "type": 20,
    "property": {
        "formatter": "0.00%",
        "formula_expression": "IF(bitable::$table[tblxxxxxxxxxxxxx].$field[fldxxxxxxx].CONTAIN(\"飞书\"),\"aaa\",\"bbb\")"
    }
}

响应体示例

{
    "code": 0,
    "data": {
        "field": {
            "field_id": "fldFuAdYEI",
            "field_name": "公式",
            "property": {
                "formatter": "0.00%",
                "formula_expression": "IF(bitable::$table[tblxxxxxxxxxxxxx].$field[fldxxxxxxx].CONTAIN(\"飞书\"),\"aaa\",\"bbb\")"
            },
            "type": 20
        }
    },
    "msg": "Success"
}

创建时间、最后更新时间字段

Property结构

名称	类型	描述	必填	是否是枚举值	可选枚举值	默认值
date_formatter	string	日期格式，参考：date_formatter	否	是	参考：date_formatter	"yyyy/MM/dd"

新增、更新字段的请求体示例

{
    "field_name": "创建时间",
    "type": 1001,
    "property": {
        "date_formatter": "yyyy/MM/dd"
    }
}

响应体示例

{
    "code": 0,
    "data": {
        "field": {
            "field_id": "fldoblwmUC",
            "field_name": "创建时间",
            "property": {
                "date_formatter": "yyyy/MM/dd"
            },
            "type": 1001
        }
    },
    "msg": "Success"
}

自动编号字段

Property结构

名称	类型	描述	必填	是否是枚举值	可选枚举值	默认值
auto_serial	app.field.property.auto_serial	自动编号	否	否	-	-
∟type	string	自动编号类型	是	是	参考：auto_serial_type	-
reformat_existing_records	bool	是否将修改应用于已有编号	否	否	-	false
∟options	app.field.property.auto_serial.options[]	自定义编号规则列表	否	否	-	-
∟type	string	规则类型	是	是	参考：rule_option_type	-
∟value	string	值	是	否	-	-

网页中编号类型与auto_serial_type的对应关系

网页中编号类型	auto_serial_type
自定义编号	"custom"
自增数字	"auto_increment_number"

网页中编号规则与rule_option_type的对应关系

网页中编号类型	rule_option_type	对应的value限制
自增数字	"system_number"	1-9
固定字符	"fixed_text"	最大长度：20
创建日期	"created_time"	可选值参考：created_time

网页中创建日期与created_time的对应关系

网页中创建日期	created_time
20220130	"yyyyMMdd"
202201	"yyyyMM"
2022	"yyyy"
0130	"MMdd"
01	"MM"
30	"dd"

新增字段的请求体示例

{
    "field_name": "自动编号",
    "property": {
        "auto_serial": {
            "type": "custom",
            "reformat_existing_records": true, 
            "options": [
                {
                    "type": "system_number",
                    "value": "3" 
                },
                {
                    "type": "fixed_text", 
                    "value": "no"
                },
                {
                    "type": "created_time",
                    "value": "yyyyMMdd"
                }
            ]
        }
    },
    "type": 1005
}

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "field": {
            "property": {
                "auto_serial": {
                    "type": "custom",
                    "options": [
                        {
                            "type": "system_number",
                            "value": "3"
                        },
                        {
                            "value": "no",
                            "type": "fixed_text"
                        },
                        {
                            "type": "created_time",
                            "value": "yyyyMMdd"
                        }
                    ]
                }
            },
            "field_id": "fldmVunQuc",
            "field_name": "自动编号",
            "type": 1005
        }
    }
}

新增字段的请求体示例

{
    "field_name": "自增数字自动编号",
    "property": {
        "auto_serial": {
            "type": "auto_increment_number",
            "reformat_existing_records": true
        }
    },
    "type": 1005
}

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "field": {
            "field_name": "自增数字自动编号",
            "type": 1005,
            "property": {
                "auto_serial": {
                    "type": "auto_increment_number"
                }
            },
            "field_id": "fldwq16vz2"
        }
    }
}

字段概述#

Property说明#

数字字段#

Property结构#

网页中数字格式与formatter的对应关系#

新增、更新字段的请求体示例#

响应体示例#

单选、多选字段#

Property结构#

新增字段的请求体示例#

响应体示例#

更新字段的请求体示例#

响应体示例#

日期字段#

Property结构#

网页中日期格式与date_formatter的对应关系#

新增、更新字段的请求体示例#

响应体示例#

人员字段#

Property结构#

新增、更新字段的请求体示例#

响应体示例#

单向关联字段#

Property结构#

新增、更新字段的请求体示例#

响应体示例#

双向关联字段#

Property结构#

新增、更新字段的请求体示例#

响应体示例#

公式字段#

Property结构#

网页中公式格式与formatter的对应关系#

新增、更新字段的请求体示例#

响应体示例#

创建时间、最后更新时间字段#

Property结构#

新增、更新字段的请求体示例#

响应体示例#

自动编号字段#

Property结构#

网页中编号类型与auto_serial_type的对应关系#

网页中编号规则与rule_option_type的对应关系#

网页中创建日期与created_time的对应关系#

新增字段的请求体示例#

响应体示例#

新增字段的请求体示例#

响应体示例#

字段概述

Property说明

数字字段

Property结构

网页中数字格式与formatter的对应关系

新增、更新字段的请求体示例

响应体示例

单选、多选字段

Property结构

新增字段的请求体示例

响应体示例

更新字段的请求体示例

响应体示例

日期字段

Property结构

网页中日期格式与date_formatter的对应关系

新增、更新字段的请求体示例

响应体示例

人员字段

Property结构

新增、更新字段的请求体示例

响应体示例

单向关联字段

Property结构

新增、更新字段的请求体示例

响应体示例

双向关联字段

Property结构

新增、更新字段的请求体示例

响应体示例

公式字段

Property结构

网页中公式格式与formatter的对应关系

新增、更新字段的请求体示例

响应体示例

创建时间、最后更新时间字段

Property结构

新增、更新字段的请求体示例

响应体示例

自动编号字段

Property结构

网页中编号类型与auto_serial_type的对应关系

网页中编号规则与rule_option_type的对应关系

网页中创建日期与created_time的对应关系

新增字段的请求体示例

响应体示例

新增字段的请求体示例

响应体示例