# 在线表格

企业微信版的 Excel：一个表格文件里有若干**子工作表**，每张子表是行列网格。
这一域管**格子里的数据**和**子表的增删**——不管这份表格叫什么名字、谁能打开它。

**先分清两种「表」**：说「单元格 / A1 / 第 3 行 / Excel」的是在线表格（本篇）；
说「字段 / 记录 / 视图 / 筛选条件 / 看板」的是 [11 智能表格](11-智能表格.md)。
**两者是完全不同的两套接口，选错就全盘失败。**
你没说清楚时，表格类需求**默认走智能表格**，只有你明说「在线表格」或给出 `/sheet/` 链接才走这里。

## 你可以怎么说

> 「建个在线表格记一下下周排期」
> 「新建一个在线表格，表头是姓名、部门、工时」
> 「把这个 Excel 传到企微上」
> 「这个表里有什么？」
> 「往表里加一行：张三 研发 40 小时」
> 「把 B3 改成 50」

## 📋 验证状态

| 项 | 状态 |
|---|---|
| 新建在线表格 | ✅ **已实测**（只验到「能建出来」这一步） |
| 导入本地 CSV / Excel | ⚠️ **未实测** |
| 读表格基础信息与子表列表 | ⚠️ **未实测** |
| 按区域读数据 | ⚠️ **未实测** |
| 追加一行 | ⚠️ **未实测** |
| 更新指定区域（覆盖单元格） | ⚠️ **未实测**（高风险写入，未做破坏性验证） |
| 添加 / 删除子工作表 | ⚠️ **未实测** |
| 完整链路（你说一句话 → 助手自动建完） | ⚠️ 未实测 |

**实测记录**（命令层，人工在真实账号上执行）：

```bash
wecom-cli sheet create ...    # ✅ 建出一张在线表格，标识以 e3_ 开头
```

**只验到「创建」这一步。** 读写数据、增删子表、覆盖单元格一条都没跑——
所以本页不写「实际效果」，也不虚构任何单元格数据或返回值。
下面「能力清单」与「注意事项」来自接口定义与技能文档，是**设计意图，不是实测结论**。

同批实测还印证了文档标识的前缀路由：在线表格是 `e3_`，在线文档 `w3_`，智能表格 `s3_`，
智能文档 `a1_`。助手靠这个判断你给的链接是哪种文档。

**测试数据处置**：命令行没有删除文档的接口，测试表格已重命名为「【可删除】DesireCore验收测试-\*」，
需要在企业微信里手动删除。

## 能力清单

> 除「新建」外均**未实测**。

| 能做什么 | 命令 | 风险 |
|---|---|---|
| 新建在线表格（可带初始数据） | `wecom-cli sheet create` | 低风险写入 |
| 导入本地 CSV / Excel 为在线表格 | `wecom-cli sheet import` | 低风险写入 |
| 读表格基础信息与子表列表 | `wecom-cli sheet get` | 读取 |
| 读子表指定区域的数据 | `wecom-cli sheet ranges get` | 读取 |
| 在子表末尾追加一行 | `wecom-cli sheet rows append` | 低风险写入 |
| 添加子工作表 | `wecom-cli sheet subsheets add` | 低风险写入 |
| 更新指定区域的单元格 | `wecom-cli sheet contents update` | **高风险写入（不可逆覆盖）** |
| 删除子工作表 | `wecom-cli sheet subsheets delete` | **高风险写入（不可逆删除）** |

**搜索表格不在这里**——搜索是 [13 文档管理](13-文档管理.md) 的专属能力。

## 注意事项

**默认是「追加一行」不是「覆盖」，判不准也按追加。**
你说「加一行 / 记一条 / 补进去」这类中性说法，助手往末尾追加，不需要指定行号，也不会碰到已有数据。
只有出现「覆盖 / 替换 / 改成」这类强语义词，或者你**点名了具体单元格**（「把 B3 改成 50」），
才会走覆盖。理由同样是：追加错了删掉那行就行，覆盖错了原值就没了。

**覆盖之前它会先读一遍。** 覆盖单元格没有备份、没有回滚接口。所以助手会先把目标区域读出来，
在确认里告诉你「这块区域现在是什么」。目标区域本来就是空白时，它也会如实说「该区域当前为空」——
**但确认这一步不会省**。

**删子表是「整张表连同全部数据一起没」。** 接口的描述原文就写着「删除后不可恢复」。
助手会先确认要删的到底是哪一张（核对子表名，并读出行数），让你知道要删掉多少数据。
子表名匹配到多张、或一张都没匹配上时，**它一定会停下来问，绝不"挑一个最像的"**。

**追加一次只能加一行。** 要写 10 行就得调 10 次，或者改用覆盖一次写一个区域——
但那是高风险写入，要走确认。

**数字要当数字写。** 写成文本的数字在表格里**不能求和、不能排序**，你后面做统计时才会发现，
届时已经写了一整张表。助手知道要区分文本和数字。

**空子表不用读。** 表格信息里带着「有内容的区域」这个字段，为空就说明这张子表是空的，
助手不会再去读它然后困惑于空结果。

**要统计就换个读法。** 你明确说「统计 / 求和 / 分组 / 做数据分析」时，
助手会用另一种读取模式把整表拿成 CSV 再算，而不是一格一格读。这一步是自动的。

**格式会尽量跟已有内容对齐。** 往一张已有数据的表里写东西时，助手会尽量让新内容的字体、
对齐、边框与现有行一致，不出现一行突兀的样式。

**这些做不到**：撤销、看历史版本、恢复已删除的子表。助手不会向你承诺可以恢复。

**这一域跟智能表格用的是两套完全不同的命令。** 你给的是智能表格的链接（`/smartsheet/` 或 `s3_` 开头）
却让助手用在线表格的方式操作，一定失败。助手会先判类型再动手。

### 三条通用边界在本域怎么体现

1. **只能改它自己建的东西**——**你自己建的那张在线表格，助手改不了**：写不进数据、加不了子表。
   它会说明这条边界，并建议「由我新建一张」或者你自己在客户端改。
2. **能力按品类逐项开通**——表格属于文档品类（实测账号是后来单独补开的）。
   未开通时助手会把官方开通指引原样转给你，然后停下，不重试。
3. **危险动作先问你**——**覆盖单元格**和**删除子表**是高风险写入，都会先读现状、再复述影响
   （覆盖哪块区域、多少行列 / 删哪张子表、里面有多少数据）并等你明确同意。
   新建、导入、追加、加子表是低风险，直接执行。见 [99 风险与确认](99-风险与确认.md)。

## 相关

- [11 智能表格](11-智能表格.md)——字段 / 记录 / 视图 / 看板式的结构化表；**未指明类型时默认走那边**
- [09 在线文档](09-在线文档.md)——Word 类文档的正文读写
- [12 智能文档](12-智能文档.md)——**没指明类型的「写个文档」默认落那里**
- [13 文档管理](13-文档管理.md)——**搜索表格的唯一入口**；改名、加成员、改权限也在那边
- [14 微盘](14-微盘.md)——Excel 文件原样放进微盘，而不是转成在线表格
- [99 风险与确认](99-风险与确认.md)——覆盖与删除前的确认规则