feishu-sheet

name: feishu-sheet description: 创建和操作飞书电子表格（Feishu Spreadsheet）。当用户说"写个飞书表格"、"创建电子表格"、"feishu sheet"等关键词时触发。 license: MIT

飞书电子表格（Feishu Sheets API）

通过飞书 Sheets API 创建和操作电子表格，支持写值、样式、公式、合并单元格、多 Sheet、数据验证等。

触发条件

• "写个飞书表格"、"创建电子表格"
• "feishu sheet"、"飞书 spreadsheet"
• "数据写到飞书表格里"

API 结构

飞书 Sheets 有两套 API：

• v3 SDK (lark_oapi.api.sheets.v3): 创建表格、查询 sheet 信息、筛选等
• v2 HTTP (/open-apis/sheets/v2/spreadsheets): 写值、样式、合并、公式等

实践中两套配合使用：v3 创建，v2 操作数据。

初始化

import os, json, requests
import lark_oapi as lark
from lark_oapi.api.sheets.v3 import *

client = lark.Client.builder() \
    .app_id(os.environ['FEISHU_APP_ID_JARVIS']) \
    .app_secret(os.environ['FEISHU_APP_SECRET_JARVIS']) \
    .domain(lark.FEISHU_DOMAIN).build()

def get_token():
    """获取 tenant_access_token 用于 v2 HTTP API。"""
    r = requests.post("https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal", json={
        "app_id": os.environ['FEISHU_APP_ID_JARVIS'],
        "app_secret": os.environ['FEISHU_APP_SECRET_JARVIS'],
    })
    return r.json()['tenant_access_token']

创建电子表格（v3 SDK）

req = CreateSpreadsheetRequest.builder() \
    .request_body(SpreadsheetBuilder().title("表格标题").build()).build()
resp = client.sheets.v3.spreadsheet.create(req)
ss_token = resp.data.spreadsheet.spreadsheet_token
url = resp.data.spreadsheet.url

查询 Sheet 列表（v3 SDK）

req = QuerySpreadsheetSheetRequest.builder().spreadsheet_token(ss_token).build()
resp = client.sheets.v3.spreadsheet_sheet.query(req)
for s in resp.data.sheets:
    print(f"sheet_id={s.sheet_id} title={s.title}")

写入数据（v2 HTTP）

BASE = "https://open.feishu.cn/open-apis/sheets/v2/spreadsheets"
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

data = {
    "valueRange": {
        "range": f"{sheet_id}!A1:C3",  # sheet_id!起始:结束
        "values": [
            ["标题1", "标题2", "标题3"],
            ["值1", 42, 3.14],
            ["值4", 100, 0.856],
        ]
    }
}
r = requests.put(f"{BASE}/{ss_token}/values", headers=headers, json=data)

支持的值类型

• 字符串: "文本"
• 整数: 42
• 浮点数: 3.14
• 公式: "=SUM(A1:A10)", "=AVERAGE(B2:B11)"
• 空值: "" 或 None
• 不支持: Python bool（用字符串 "TRUE"/"FALSE" 代替）

设置样式（v2 HTTP）

style_data = {
    "data": [
        {
            "ranges": [f"{sheet_id}!A1:F1"],
            "style": {
                "font_size": 12,         # 字号
                "bold": True,            # 粗体
                "italic": True,          # 斜体
                "foreColor": "#FFFFFF",  # 文字颜色（hex）
                "backColor": "#4C6EF5", # 背景色（hex）
                "hAlign": 0,            # 水平对齐：0=左 1=中 2=右
                "vAlign": 0,            # 垂直对齐：0=上 1=中 2=下
                "strikethrough": True,   # 删除线
                "underline": True,       # 下划线
            }
        }
    ]
}
r = requests.put(f"{BASE}/{ss_token}/styles_batch_update", headers=headers, json=style_data)

一次设置多个范围

data 数组中可以放多个 {ranges, style} 对象，一次 API 调用设置多个区域的样式。

合并单元格（v2 HTTP）

merge_data = {
    "range": f"{sheet_id}!A1:D1",
    "mergeType": "MERGE_ALL"  # MERGE_ALL | MERGE_ROWS | MERGE_COLUMNS
}
r = requests.post(f"{BASE}/{ss_token}/merge_cells", headers=headers, json=merge_data)

管理 Sheet（v2 HTTP）

新增 Sheet

data = {
    "requests": [{
        "addSheet": {
            "properties": {
                "title": "新工作表",
                "index": 1  # 位置
            }
        }
    }]
}
r = requests.post(f"{BASE}/{ss_token}/sheets_batch_update", headers=headers, json=data)
new_sheet_id = r.json()['data']['replies'][0]['addSheet']['properties']['sheetId']

重命名 Sheet

data = {
    "requests": [{
        "updateSheet": {
            "properties": {
                "sheetId": sheet_id,
                "title": "新名称"
            }
        }
    }]
}
r = requests.post(f"{BASE}/{ss_token}/sheets_batch_update", headers=headers, json=data)

删除 Sheet

data = {"requests": [{"deleteSheet": {"sheetId": sheet_id}}]}
r = requests.post(f"{BASE}/{ss_token}/sheets_batch_update", headers=headers, json=data)

设置列宽（v2 HTTP）

data = {
    "dimension": {
        "sheetId": sheet_id,
        "majorDimension": "COLUMNS",
        "startIndex": 3,  # 从 1 开始！0 会报错
        "endIndex": 3
    },
    "dimensionProperties": {
        "fixedSize": 250  # 像素
    }
}
r = requests.put(f"{BASE}/{ss_token}/dimension_range", headers=headers, json=data)

注意: startIndex 必须 > 0，索引从 1 开始，不是 0。

公式

公式作为字符串值写入，飞书会自动计算：

values = [["合计", "=SUM(B2:B10)", "=AVERAGE(C2:C10)", "=MAX(D2:D10)"]]

常用公式：SUM, AVERAGE, COUNT, MAX, MIN, IF, VLOOKUP, CONCATENATE

斑马纹（交替行颜色）

even_rows = [f"{sheet_id}!A{i}:F{i}" for i in range(2, 12, 2)]
style_data = {
    "data": [{"ranges": even_rows, "style": {"backColor": "#F8F9FA"}}]
}

常见颜色参考

注意事项

• token 有效期: tenant_access_token 有效期 2 小时，长时间操作需要刷新
• Rate limit: 约 100 次/分钟，批量操作建议合并 ranges
• Range 格式: {sheet_id}!A1:F10，sheet_id 是查询返回的短 ID（如 be5f93）
• 布尔值: Python True/False 不支持直接写入，用字符串 "TRUE"/"FALSE"
• startIndex: 列宽/行高 API 的 index 从 1 开始，不是 0
• URL 格式: https://xcn6w52qes4g.feishu.cn/sheets/{spreadsheet_token}（域名取决于租户）

完整工作流程

1. 创建表格 → v3 SDK CreateSpreadsheetRequest → 拿到 spreadsheet_token
2. 查询 sheet_id → v3 SDK QuerySpreadsheetSheetRequest
3. 获取 token → HTTP POST /auth/v3/tenant_access_token/internal
4. 写数据 → v2 HTTP PUT /values
5. 设样式 → v2 HTTP PUT /styles_batch_update
6. 合并/列宽等 → v2 HTTP 各端点
7. 返回链接 → https://xxx.feishu.cn/sheets/{token}