Files

T

2026-09-02 11:44:52 +08:00

7.6 KiB

Raw Blame History

字段类型 config 规范（field create / table create / field update）

适用命令：dws aitable field create、dws aitable table create --fields、dws aitable field update --config

本文件是 DWS AI 表格字段 config 的 source of truth。创建/更新字段时，必须严格按此规范构造 JSON。

1. 顶层规则

table create --fields 和 field create --fields 中每个字段对象：{"fieldName":"xxx", "type":"xxx", "config":{...}}
field create --name --type --config 中 config 单独传 JSON 字符串
field update --config 只传 config 部分
不需要 config 的类型（如 text、checkbox、attachment）可省略 config 字段

2. 字段类型速查

type	需要 config	config 核心字段	说明
`text`	❌	—	纯文本
`number`	可选	`formatter`	数字格式
`singleSelect`	✅	`options`	单选
`multipleSelect`	✅	`options`	多选
`date`	可选	`formatter`	日期格式
`currency`	可选	`currencyType`, `formatter`	货币
`progress`	可选	`formatter`, `min`, `max`, `customizeRange`	进度条
`rating`	可选	`min`, `max`, `icon`	评分
`checkbox`	❌	—	勾选框
`user`	可选	`multiple`	人员
`department`	可选	`multiple`	部门
`group`	可选	`multiple`	群组
`url`	❌	—	链接
`richText`	❌	—	富文本
`telephone`	❌	—	电话
`email`	❌	—	邮箱
`attachment`	❌	—	附件
`geolocation`	❌	—	地理位置
`formula`	✅	`formula`	公式（只读字段）
`unidirectionalLink`	✅	`linkedTableId`, `multiple`	单向关联
`bidirectionalLink`	✅	`linkedTableId`, `multiple`	双向关联
`creator`	❌	—	系统字段：创建人（只读）
`lastModifier`	❌	—	系统字段：最后编辑人（只读）
`createdTime`	❌	—	系统字段：创建时间（只读）
`lastModifiedTime`	❌	—	系统字段：最后编辑时间（只读）

3. 各类型 config 详解

3.1 number（数字）

config 字段：formatter

可选值：

INT — 整数
FLOAT_1 — 1 位小数
FLOAT_2 — 2 位小数（默认）
FLOAT_3 — 3 位小数
FLOAT_4 — 4 位小数
THOUSAND — 千分位整数
THOUSAND_FLOAT — 千分位 + 小数
PERCENT — 百分比（整数）
PERCENT_FLOAT — 百分比（小数）

{"fieldName": "工时", "type": "number", "config": {"formatter": "FLOAT_2"}}

{"fieldName": "完成率", "type": "number", "config": {"formatter": "PERCENT"}}

3.2 singleSelect / multipleSelect（单选 / 多选）

config 字段：options（必填）

options 结构：

options 是数组，每项至少包含 name
创建时只传 name，id 由系统生成
更新时：已有选项必须回传原 id（从 field get 获取），新增选项不传 id

{
  "fieldName": "优先级",
  "type": "singleSelect",
  "config": {
    "options": [
      {"name": "紧急"},
      {"name": "高"},
      {"name": "中"},
      {"name": "低"}
    ]
  }
}

更新已有字段时（保留原选项 + 新增）：

{
  "options": [
    {"id": "opt_existing_1", "name": "紧急"},
    {"id": "opt_existing_2", "name": "高"},
    {"id": "opt_existing_3", "name": "中"},
    {"name": "极低"}
  ]
}

更新 options 是全量覆盖，不是追加！不传的旧选项会被删除，关联的单元格数据丢失。

3.3 date（日期）

config 字段：formatter

可选值：

YYYY-MM-DD（默认）
YYYY-MM-DD HH:mm
YYYY-MM-DD HH:mm:ss
YYYY/MM/DD
YYYY/MM/DD HH:mm

{"fieldName": "截止日期", "type": "date", "config": {"formatter": "YYYY-MM-DD"}}

{"fieldName": "创建时间", "type": "date", "config": {"formatter": "YYYY-MM-DD HH:mm"}}

3.4 currency（货币）

config 字段：currencyType（必填）、formatter（可选）

currencyType 可选值： CNY | HKD | USD | EUR | GBP | MOP | VND | JPY | KRW | AED | AUD | BRL | CAD | CHF | INR | IDR | MXN | MYR | PHP | PLN | RUB | SGD | THB | TRY | TWD

formatter 可选值（控制小数位）：INT | FLOAT_1 | FLOAT_2（默认）| FLOAT_3 | FLOAT_4

{"fieldName": "预算", "type": "currency", "config": {"currencyType": "CNY", "formatter": "FLOAT_2"}}

3.5 progress（进度）

config 字段：formatter（固定为 PERCENT）、customizeRange、min、max

默认范围：0~1（即 0%~100%）
自定义范围时 customizeRange 必须为 true

{"fieldName": "完成度", "type": "progress", "config": {"formatter": "PERCENT"}}

自定义范围：

{"fieldName": "进度", "type": "progress", "config": {"formatter": "PERCENT", "customizeRange": true, "min": 0, "max": 1}}

3.6 rating（评分）

config 字段：min、max、icon

min：固定为 1
max：1~10，默认 5
icon：默认 star

{"fieldName": "满意度", "type": "rating", "config": {"min": 1, "max": 5, "icon": "star"}}

3.7 user / department / group（人员 / 部门 / 群组）

config 字段：multiple

multiple：true（多选，默认）| false（单选）

{"fieldName": "负责人", "type": "user", "config": {"multiple": false}}

{"fieldName": "协作部门", "type": "department", "config": {"multiple": true}}

3.8 formula（公式）

config 字段：formula（必填）

公式中引用字段使用方括号 + 字段名：[字段名]
支持的函数：参考钉钉 AI 表格公式文档

{"fieldName": "合计", "type": "formula", "config": {"formula": "[单价] * [数量]"}}

{"fieldName": "是否逾期", "type": "formula", "config": {"formula": "IF([截止日期] < NOW(), \"是\", \"否\")"}}

⚠️ formula 字段创建后为只读，不能通过 record create/update 写入值。

3.9 unidirectionalLink（单向关联）

config 字段：linkedTableId（必填）、multiple

linkedTableId：目标表的 tableId
multiple：true（多选，默认）| false（单选）

{"fieldName": "关联项目", "type": "unidirectionalLink", "config": {"linkedTableId": "tblXXXXXX", "multiple": true}}

3.10 bidirectionalLink（双向关联）