# 飞书表格能力研究
## 一、三种表格类型对比
| 类型 | API 路径 | 标识符 | 适用场景 |
|------|---------|--------|---------|
| 文档内嵌表格 | `/docx/v1/documents/{id}/blocks` | block_type=31 | 方案对比表、简单数据展示 |
| 电子表格 | `/sheets/v3/spreadsheets` | spreadsheetToken | Excel 式数据分析、公式计算 |
| 多维表格 | `/bitable/v1/apps` | app_token + table_id | 数据库、任务管理、CRM |
## 二、文档内嵌表格 (Table Block)
### 2.1 Block 结构
```
Table (block_type=31)
├── property: { row_size, column_size, ... }
└── children: [TableCell...]
└── TableCell (block_type=32)
└── children: [Text Block...]
```
### 2.2 创建表格的 API
```
POST /docx/v1/documents/{document_id}/blocks/{block_id}/children
{
"children": [{
"block_type": 31,
"table": {
"property": {
"row_size": 3,
"column_size": 3,
"column_width": [100, 100, 100],
"merge_info": [] // 合并单元格
},
"cells": [
// 按行展开的单元格内容
]
}
}]
}
```
### 2.3 关键参数
- `row_size`: 行数
- `column_size`: 列数
- `column_width`: 列宽数组（像素）
- `merge_info`: 合并单元格信息 [{row_span, col_span}]
- `header_row`: 是否有表头行
- `header_column`: 是否有表头列
## 三、电子表格 (Sheets)
### 3.1 API 概览
| 接口 | 功能 |
|------|------|
| POST /sheets/v3/spreadsheets | 创建电子表格 |
| GET /sheets/v3/spreadsheets/{token} | 获取表格信息 |
| POST /sheets/v3/spreadsheets/{token}/sheets | 新增工作表 |
| PUT /sheets/v3/spreadsheets/{token}/values | 写入数据 |
| GET /sheets/v3/spreadsheets/{token}/values/{range} | 读取数据 |
### 3.2 创建电子表格
```
POST /sheets/v3/spreadsheets
{
"title": "方案对比表",
"folder_token": "xxx" // 可选，目标文件夹
}
Response:
{
"spreadsheet": {
"spreadsheet_token": "shtcnxxxxxxx",
"title": "方案对比表",
"url": "https://xxx.feishu.cn/sheets/shtcnxxxxxxx"
}
}
```
### 3.3 写入数据
```
PUT /sheets/v3/spreadsheets/{token}/values
{
"valueRange": {
"range": "Sheet1!A1:C3",
"values": [
["维度", "方案A", "方案B"],
["成本", "10万", "5万"],
["复杂度", "高", "低"]
]
}
}
```
### 3.4 高级功能
- 公式: `=SUM(A1:A10)`
- 条件格式
- 数据校验
- 筛选
- 图表
## 四、多维表格 (Bitable)
### 4.1 概念
- **App (应用)**: 一个多维表格文件
- **Table (数据表)**: App 内的一张表
- **Field (字段)**: 列定义（文本、数字、日期、关联...）
- **Record (记录)**: 一行数据
### 4.2 API 概览
| 接口 | 功能 |
|------|------|
| POST /bitable/v1/apps | 创建多维表格 |
| POST /bitable/v1/apps/{app_token}/tables | 创建数据表 |
| POST /bitable/v1/apps/{app_token}/tables/{table_id}/fields | 创建字段 |
| POST /bitable/v1/apps/{app_token}/tables/{table_id}/records | 创建记录 |
### 4.3 字段类型
- 1: 文本
- 2: 数字
- 3: 单选
- 4: 多选
- 5: 日期
- 7: 复选框
- 11: 人员
- 15: 链接
- 17: 附件
- 18: 单向关联
- 21: 双向关联
- 1001: 公式
- 1002: 自动编号
## 五、场景推荐
| 场景 | 推荐类型 | 原因 |
|------|---------|------|
| 方案对比表（文档内） | 文档内嵌表格 | 简单、内联展示 |
| 数据分析、计算 | 电子表格 | 支持公式 |
| 任务跟踪、项目管理 | 多维表格 | 字段类型丰富、视图多样 |
| 数据汇总报表 | 电子表格 | 易于格式化 |
| API 接口文档 | 文档内嵌表格 | 简洁直观 |
## 六、MCP 工具设计
### 6.1 文档内嵌表格
```typescript
feishu_insert_table({
document_id: "xxx",
markdown_table: `
| 维度 | 方案A | 方案B |
|------|-------|-------|
| 成本 | 10万 | 5万 |
`,
// 或结构化输入
headers: ["维度", "方案A", "方案B"],
rows: [
["成本", "10万", "5万"],
["复杂度", "高", "低"]
],
header_row: true, // 表头样式
column_width: [100, 150, 150] // 可选
})
```
### 6.2 电子表格
```typescript
feishu_create_spreadsheet({
title: "数据分析表",
folder_token: "xxx", // 可选
sheets: [{
name: "Sheet1",
data: [
["A", "B", "C"],
[1, 2, "=A2+B2"]
]
}]
})
feishu_write_spreadsheet({
spreadsheet_token: "xxx",
range: "Sheet1!A1:C3",
values: [[...], [...]]
})
```
### 6.3 多维表格
```typescript
feishu_create_bitable({
name: "项目任务表",
fields: [
{ name: "任务名", type: 1 }, // 文本
{ name: "负责人", type: 11 }, // 人员
{ name: "截止日期", type: 5 }, // 日期
{ name: "状态", type: 3, options: ["待处理", "进行中", "已完成"] }
],
records: [...]
})
```
