cc-lark 0.1.1

package/skills/feishu-bitable/references/field-properties.md

@@ -0,0 +1,763 @@
+# 飞书多维表格字段 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)