From 319b51b1f3e76e69f223a2d68e6e5d7a2b2c0fb3 Mon Sep 17 00:00:00 2001 From: / Date: Mon, 13 Apr 2026 22:51:53 +0800 Subject: [PATCH] feat(sheets): add value format documentation for formula and special types Document the correct object format for writing formulas, URLs with text, mentions, and dropdown lists via --values parameter. Add examples contrasting correct object format vs incorrect plain string. Co-Authored-By: Claude Opus 4.6 (1M context) --- skill-template/domains/sheets.md | 36 +++++++++++++++++++++++++++++++- skills/lark-sheets/SKILL.md | 34 ++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+), 1 deletion(-) diff --git a/skill-template/domains/sheets.md b/skill-template/domains/sheets.md index 9edc430adb..de52d837ec 100644 --- a/skill-template/domains/sheets.md +++ b/skill-template/domains/sheets.md @@ -126,4 +126,38 @@ lark-cli sheets spreadsheet.sheet.filters update \ **常见错误：** - `Wrong Filter Value`：筛选已存在，需要先 delete 再 create -- `Excess Limit`：update 时重复添加同一列条件 \ No newline at end of file +- `Excess Limit`：update 时重复添加同一列条件 + +### 单元格数据类型 + +接受二维数组的 shortcut（`+write`/`+append` 的 `--values`、`+create` 的 `--data`）中，每个单元格值支持以下类型。**公式、带文本链接、@人、@文档、下拉列表必须使用对象格式**，直接传字符串会被当作纯文本存储。 + +| 类型 | 写入格式 | 示例 | +|------|---------|------| +| 字符串 | `"文本"` | `"hello"` | +| 数字 | `数字` | `123`、`3.14` | +| 日期 | `数字`（自 1899-12-30 起的天数，需先设单元格日期格式） | `42101` | +| 链接（纯 URL） | `"URL 字符串"` | `"https://example.com"` | +| 链接（带文本） | `{"type":"url","text":"显示文本","link":"URL"}` | `{"type":"url","text":"飞书","link":"https://www.feishu.cn"}` | +| 邮箱 | `"邮箱字符串"` | `"user@example.com"` | +| **公式** | `{"type":"formula","text":"=公式"}` | `{"type":"formula","text":"=SUM(A1:A10)"}` | +| @人 | `{"type":"mention","text":"标识","textType":"email\|openId\|unionId","notify":false}` | `{"type":"mention","text":"user@example.com","textType":"email","notify":false}`（notify 可选，默认 false；仅在用户明确要求通知时设为 true） | +| @文档 | `{"type":"mention","textType":"fileToken","text":"token","objType":"类型"}` | `{"type":"mention","textType":"fileToken","text":"shtXXX","objType":"sheet"}` | +| 下拉列表 | `{"type":"multipleValue","values":[值1,值2]}` | `{"type":"multipleValue","values":["选项A","选项B"]}` | + +**写入公式示例**： + +```bash +# ✅ 正确：使用对象格式 +lark-cli sheets +write --url "URL" --sheet-id "sheetId" --range "C6" \ + --values '[[{"type":"formula","text":"=SUM(C2:C5)"}]]' + +# ❌ 错误：直接传字符串，会被存为纯文本 +lark-cli sheets +write --url "URL" --sheet-id "sheetId" --range "C6" \ + --values '[["=SUM(C2:C5)"]]' +``` + +**限制**： +- 公式不支持跨表引用（IMPORTRANGE） +- @人仅支持同租户用户，单次最多 50 人 +- 下拉列表需先调用设置下拉列表接口，值中的字符串不能包含逗号 diff --git a/skills/lark-sheets/SKILL.md b/skills/lark-sheets/SKILL.md index 408939f7eb..6cda35ee61 100644 --- a/skills/lark-sheets/SKILL.md +++ b/skills/lark-sheets/SKILL.md @@ -141,6 +141,40 @@ lark-cli sheets spreadsheet.sheet.filters update \ - `Wrong Filter Value`：筛选已存在，需要先 delete 再 create - `Excess Limit`：update 时重复添加同一列条件 +### 单元格数据类型 + +接受二维数组的 shortcut（`+write`/`+append` 的 `--values`、`+create` 的 `--data`）中，每个单元格值支持以下类型。**公式、带文本链接、@人、@文档、下拉列表必须使用对象格式**，直接传字符串会被当作纯文本存储。 + +| 类型 | 写入格式 | 示例 | +|------|---------|------| +| 字符串 | `"文本"` | `"hello"` | +| 数字 | `数字` | `123`、`3.14` | +| 日期 | `数字`（自 1899-12-30 起的天数，需先设单元格日期格式） | `42101` | +| 链接（纯 URL） | `"URL 字符串"` | `"https://example.com"` | +| 链接（带文本） | `{"type":"url","text":"显示文本","link":"URL"}` | `{"type":"url","text":"飞书","link":"https://www.feishu.cn"}` | +| 邮箱 | `"邮箱字符串"` | `"user@example.com"` | +| **公式** | `{"type":"formula","text":"=公式"}` | `{"type":"formula","text":"=SUM(A1:A10)"}` | +| @人 | `{"type":"mention","text":"标识","textType":"email\|openId\|unionId","notify":false}` | `{"type":"mention","text":"user@example.com","textType":"email","notify":false}`（notify 可选，默认 false；仅在用户明确要求通知时设为 true） | +| @文档 | `{"type":"mention","textType":"fileToken","text":"token","objType":"类型"}` | `{"type":"mention","textType":"fileToken","text":"shtXXX","objType":"sheet"}` | +| 下拉列表 | `{"type":"multipleValue","values":[值1,值2]}` | `{"type":"multipleValue","values":["选项A","选项B"]}` | + +**写入公式示例**： + +```bash +# ✅ 正确：使用对象格式 +lark-cli sheets +write --url "URL" --sheet-id "sheetId" --range "C6" \ + --values '[[{"type":"formula","text":"=SUM(C2:C5)"}]]' + +# ❌ 错误：直接传字符串，会被存为纯文本 +lark-cli sheets +write --url "URL" --sheet-id "sheetId" --range "C6" \ + --values '[["=SUM(C2:C5)"]]' +``` + +**限制**： +- 公式不支持跨表引用（IMPORTRANGE） +- @人仅支持同租户用户，单次最多 50 人 +- 下拉列表需先调用设置下拉列表接口，值中的字符串不能包含逗号 + ## Shortcuts（推荐优先使用） Shortcut 是对常用操作的高级封装（`lark-cli sheets + [flags]`）。有 Shortcut 的操作优先使用。