多维表格工具

本文档详细介绍多维表格（Bitable）相关的工具使用方法。

⚠️ 重要提示

• 默认表空行：创建多维表格时自带的默认表中有空记录，插入数据前建议先删除
• 字段类型：不同字段类型对值格式要求完全不同，务必先查询字段类型
• 批量上限：单次最多 500 条记录
• 并发限制：同一数据表不支持并发写，需串行调用

工具列表

工具	功能
feishu_bitable_app	管理多维表格（创建、删除、复制）
feishu_bitable_app_table	管理数据表（创建、删除）
feishu_bitable_app_table_field	管理字段（创建、查询、删除）
feishu_bitable_app_table_record	管理记录（增删改查、批量操作）
feishu_bitable_app_table_view	管理视图（创建、切换）

资源层级

多维表格 App (app_token)
  └── 数据表 Table (table_id)
        ├── 字段 Field (field_id)
        ├── 记录 Record (record_id)
        └── 视图 View (view_id)

字段类型与值格式

type	字段类型	值格式	示例
1	文本	字符串	"Hello"
2	数字	数字	123
3	单选	字符串	"选项1"
4	多选	字符串数组	["选项1", "选项2"]
5	日期	毫秒时间戳	1674206443000
7	复选框	布尔值	true
11	人员	对象数组	[{id: "ou_xxx"}]
13	电话	字符串	"13800138000"
15	超链接	对象	{link: "url", text: "文本"}
17	附件	对象数组	[{file_token: "xxx"}]
18	公式	只读	由公式自动计算
20	进度	数字 0-100	50
22	评分	数字 1-5	3
24	货币	数字	99.99
26	地理位置	对象	{lat: 39.9, lng: 116.4}
27	单向关联	字符串数组（record_id）	["recxxx"]
28	双向关联	字符串数组（record_id）	["recxxx"]
30	创建人	自动填充	只读
31	修改人	自动填充	只读
32	按钮	元数据	仅 UI
33	链接	对象	{link: "url"}
34	成员多选	对象数组	[{id: "ou_xxx"}, {id: "ou_yyy"}]

高级字段配置

单选字段（type: 3）

{
  "field_name": "状态",
  "type": 3,
  "property": {
    "options": ["待处理", "进行中", "已完成"]
  }
}

数字字段（type: 2）

{
  "field_name": "价格",
  "type": 2,
  "property": {
    "formatter": "0.00",
    "symbol": "¥",
    "precision": 2
  }
}

关联字段（type: 27/28）

{
  "field_name": "关联客户",
  "type": 27,
  "property": {
    "table_id": "tblxxx",
    "foreign_table_id": "tbl_yyy"
  }
}

常见错误

错误码	错误类型	解决方案
1254064	日期格式错误	使用毫秒时间戳，不是秒
1254068	超链接格式错误	使用 {link, text} 对象格式
1254066	人员字段格式错误	使用 [{id: "ou_xxx"}] 格式
1254015	字段类型不匹配	先查询字段类型，按类型构造值
1254104	批量超限	分批调用，每批 ≤ 500
1254291	并发冲突	串行调用，延迟 0.5-1 秒

使用示例

查询字段

{
  "action": "list",
  "app_token": "S404bxxxxx",
  "table_id": "tblxxxxx"
}

插入记录

{
  "action": "create",
  "app_token": "S404bxxxxx",
  "table_id": "tblxxxxx",
  "fields": {
    "客户名称": "字节跳动",
    "负责人": [{"id": "ou_xxx"}],
    "签约日期": 1674206443000,
    "状态": "进行中"
  }
}

批量导入

{
  "action": "batch_create",
  "app_token": "S404bxxxxx",
  "table_id": "tblxxxxx",
  "records": [
    {"fields": {"客户名称": "客户A", "状态": "进行中"}},
    {"fields": {"客户名称": "客户B", "状态": "已完成"}}
  ]
}

高级筛选

{
  "action": "list",
  "app_token": "S404bxxxxx",
  "table_id": "tblxxxxx",
  "filter": {
    "conjunction": "and",
    "conditions": [
      {"field_name": "状态", "operator": "is", "value": ["进行中"]},
      {"field_name": "签约日期", "operator": "isGreater", "value": ["ExactDate", "1672531200000"]}
    ]
  }
}

排序

{
  "action": "list",
  "app_token": "S404bxxxxx",
  "table_id": "tblxxxxx",
  "sort": [
    {"field_name": "签约日期", "desc": true},
    {"field_name": "客户名称", "desc": false}
  ]
}

分页

{
  "action": "list",
  "app_token": "S404bxxxxx",
  "table_id": "tblxxxxx",
  "page_size": 100,
  "page_token": "xxx_token_from_previous_response"
}

筛选操作符

操作符	说明
is	等于
isNot	不等于
contains	包含
doesNotContain	不包含
isEmpty	为空
isNotEmpty	不为空
isGreater	大于
isGreaterEqual	大于等于
isLess	小于
isLessEqual	小于等于

视图管理

创建视图

{
  "action": "create",
  "app_token": "S404bxxxxx",
  "table_id": "tblxxxxx",
  "view_name": "我的视图",
  "view_type": "kanban"
}

视图类型

类型	说明
grid	表格视图（默认）
kanban	看板视图
gallery	画廊视图
gantt	甘特图视图
form	表单视图