@yosai/cli 0.2.1-test.8 → 0.2.1-test.9

package/dist/skills/yos-doc-sheet/references/SHEET_DATA_API.md

@@ -0,0 +1,356 @@
+# 表格页数据字段全量枚举
+
+> 按 Univer **`workbook.save()`** 快照（`IWorkbookData`）逐层列出字段与含义。  
+> 依据：`@univerjs/core` 类型（本仓库依赖 `^0.25.1`）+ 本包 Demo / 导入导出精简结构。  
+> 表格无内嵌服务端 HTTP；持久化由宿主自行完成。本文是工作簿 JSON 契约。
+>
+> **Agent 生成请用精简契约** [`agent/AGENT_SCHEMA.md`](./agent/AGENT_SCHEMA.md) + `yos-sheet validate`，勿把本文整份塞进 prompt。
+
+---
+
+## 0. 读写约定
+
+| 方向 | API | 说明 |
+| ---- | --- | ---- |
+| 读取快照 | `getActiveWorkbook().save()` | 返回完整 `IWorkbookData`（含样式、合并、插件 `resources` 等） |
+| 加载快照 | `createWorkbook(snapshot)` | 用同一结构创建 / 替换工作簿 |
+| 导出 xlsx | `exportExcel` → `exportWorkbookToXlsx`（ExcelJS） | 值 / 公式 + 基础样式（背景色 / 字体 / 对齐）+ 合并；不含图表 |
+| 导入 xlsx | `importExcel` → `importWorkbookFromXlsx`（ExcelJS） | 产出精简快照（值 / 公式 / 基础样式 / 合并），再 `createWorkbook` |
+
+Demo 初始数据见 `SheetEditor` 内 `buildDemoWorkbook`；可粘贴整本骨架见 [`fixtures/sheet-workbook.template.json`](./fixtures/sheet-workbook.template.json)。
+
+布尔类字段在 Univer 里多用数字枚举 **`BooleanNumber`**：`0` = false，`1` = true。
+
+---
+
+## 1. 工作簿根（`IWorkbookData`）
+
+```json
+{
+  "id": "sheet-demo",
+  "name": "表格 Demo",
+  "appVersion": "0.25.1",
+  "locale": "zhCN",
+  "styles": {},
+  "sheetOrder": ["sheet-1"],
+  "sheets": { "sheet-1": { /* IWorksheetData */ } },
+  "resources": []
+}
+```
+
+| 参数 | 类型 | 必有 | 含义 | 取值 / 说明 |
+| ---- | ---- | ---- | ---- | ----------- |
+| `id` | `string` | 是 | 工作簿 unit id | 全生命周期建议稳定不变 |
+| `name` | `string` | 是 | 工作簿显示名 | |
+| `appVersion` | `string` | 是* | 模型版本 | 通常为 Univer 版本，如 `"0.25.1"`；缺省时运行时会补 |
+| `locale` | `string` | 是* | 语言 | 本包默认 `"zhCN"`（`LocaleType.ZH_CN`） |
+| `styles` | `Record<string, IStyleData \| null>` | 是* | 样式表 | key 为样式 id，单元格 `s` 引用 |
+| `sheetOrder` | `string[]` | 是 | sheet id 顺序 | 与底部页签顺序一致 |
+| `sheets` | `Record<string, Partial<IWorksheetData>>` | 是 | sheet 字典 | key = sheet `id` |
+| `defaultStyle` | `IStyleData \| string` | 否 | 工作簿默认样式 | 可为样式对象或样式 id |
+| `resources` | `{ name, data, id? }[]` | 否 | 插件资源 | 筛选 / 条件格式 / 批注等插件状态；`data` 多为 JSON 字符串 |
+| `rev` | `number` | 否 | 协同修订号 | 协作场景；本包未接协作 |
+| `custom` | `object` | 否 | 宿主自定义字段 | 勿与 Univer 保留字段冲突 |
+
+\* Demo / xlsx 导入的精简快照可省略 `appVersion` / `locale` / `styles`，`createWorkbook` 会补默认值；**生产持久化建议存 `save()` 全量结果**。
+
+---
+
+## 2. 工作表（`IWorksheetData`）
+
+```json
+{
+  "id": "sheet-1",
+  "name": "Sheet1",
+  "tabColor": "",
+  "hidden": 0,
+  "rowCount": 100,
+  "columnCount": 20,
+  "defaultColumnWidth": 88,
+  "defaultRowHeight": 24,
+  "mergeData": [],
+  "cellData": {},
+  "rowData": {},
+  "columnData": {},
+  "rowHeader": { "width": 46 },
+  "columnHeader": { "height": 20 },
+  "showGridlines": 1,
+  "rightToLeft": 0,
+  "freeze": { "xSplit": 0, "ySplit": 0, "startRow": -1, "startColumn": -1 }
+}
+```
+
+| 参数 | 类型 | 含义 | 说明 |
+| ---- | ---- | ---- | ---- |
+| `id` | `string` | 工作表 id | 稳定 id；出现在 `sheetOrder` |
+| `name` | `string` | 页签名 | Excel 限制约 31 字符 |
+| `tabColor` | `string` | 页签颜色 | 空字符串表示默认 |
+| `hidden` | `BooleanNumber` | 是否隐藏 | `0` / `1` |
+| `rowCount` | `number` | 行数 | 本包上限 `10000`（`MAX_SHEET_ROW_COUNT`） |
+| `columnCount` | `number` | 列数 | Demo 默认 `20` |
+| `defaultColumnWidth` | `number` | 默认列宽（px） | |
+| `defaultRowHeight` | `number` | 默认行高（px） | |
+| `mergeData` | `IRange[]` | 合并单元格 | 见 §5 |
+| `cellData` | 稀疏矩阵 | 单元格内容 | 见 §3；key 为行 / 列 **数字字符串或数字** |
+| `rowData` | 稀疏数组对象 | 行属性 | 见 §6 |
+| `columnData` | 稀疏数组对象 | 列属性 | 见 §6 |
+| `rowHeader` | `{ width, hidden? }` | 行号栏 | |
+| `columnHeader` | `{ height, hidden? }` | 列标栏 | |
+| `showGridlines` | `BooleanNumber` | 显示网格线 | |
+| `gridlinesColor` | `string` | 网格线颜色 | 可选 |
+| `rightToLeft` | `BooleanNumber` | 从右到左 | |
+| `freeze` | `IFreeze` | 冻结窗格 | 见 §5 |
+| `defaultStyle` | `IStyleData \| string` | 表级默认样式 | 可选 |
+| `zoomRatio` / `scrollTop` / `scrollLeft` | `number` | 视图状态 | 已 deprecated，可忽略 |
+| `custom` | `object` | 宿主自定义 | 可选 |
+
+`cellData` 形态（稀疏，只存有内容的格）：
+
+```json
+{
+  "0": {
+    "0": { "v": "列1" },
+    "1": { "v": 2, "t": 2 }
+  },
+  "1": {
+    "3": { "f": "=B2*C2", "v": 20, "t": 2 }
+  }
+}
+```
+
+行 / 列下标均为 **0-based**。
+
+---
+
+## 3. 单元格（`ICellData`）
+
+| 参数 | 类型 | 含义 | 说明 |
+| ---- | ---- | ---- | ---- |
+| `v` | `string \| number \| boolean \| null` | 显示 / 原始值 | 公式格常同时有计算结果 |
+| `t` | `CellValueType` | 值类型 | `1` STRING / `2` NUMBER / `3` BOOLEAN / `4` FORCE_STRING |
+| `f` | `string \| null` | 公式 | 含前导 `=`，如 `"=SUM(A1:B2)"` |
+| `s` | `string \| IStyleData \| null` | 样式 | **推荐**写样式 id（指向根 `styles`）；也可内联对象 |
+| `si` | `string \| null` | 公式 id | 公式引擎内部关联 |
+| `p` | `IDocumentData \| null` | 富文本文档 | 单元格内富文本；一般可忽略 |
+| `ref` / `xf` | `string` | 数组公式 / Excel 前缀 | 内部字段，宿主通常不手写 |
+| `custom` | `object` | 宿主自定义 | 可选 |
+
+本包 xlsx 导入导出认 **`v` / `f`（及可选 `t`）**，以及内联 / 引用的基础样式 **`s`**（背景色、字体、对齐）与表级 **`mergeData`**。
+
+---
+
+## 4. 样式（`IStyleData`）
+
+挂在工作簿根 `styles`，由单元格 `s` 引用：
+
+```json
+{
+  "styles": {
+    "header": {
+      "bl": 1,
+      "ht": 2,
+      "bg": { "rgb": "#E8F3FF" },
+      "cl": { "rgb": "#1F2329" }
+    }
+  }
+}
+```
+
+常用字段（缩写来自 Univer）：
+
+| 参数 | 含义 | 取值 |
+| ---- | ---- | ---- |
+| `ff` | 字体 | 字体名字符串 |
+| `fs` | 字号（pt） | `number` |
+| `it` | 斜体 | `BooleanNumber` |
+| `bl` | 粗体 | `BooleanNumber` |
+| `ul` / `st` / `ol` | 下划线 / 删除线 / 上划线 | `ITextDecoration`（`s` 是否显示等） |
+| `bg` | 背景色 | `{ "rgb": "#RRGGBB" }` 或主题色 |
+| `cl` | 前景色（文字） | 同 `bg` |
+| `bd` | 边框 | `{ t, r, b, l }` → `{ s: BorderStyleTypes, cl }` |
+| `ht` | 水平对齐 | `1` LEFT / `2` CENTER / `3` RIGHT / `4` JUSTIFIED … |
+| `vt` | 垂直对齐 | `1` TOP / `2` MIDDLE / `3` BOTTOM |
+| `tb` | 换行策略 | `1` OVERFLOW / `2` CLIP / `3` WRAP |
+| `tr` | 文字旋转 | `{ a: 角度, v?: BooleanNumber }` |
+| `pd` | 内边距 | `{ t, r, b, l }` |
+| `n` | 数字格式 | `{ "pattern": "0.00" }` 等 |
+| `va` | 上标 / 下标 | BaselineOffset |
+
+`BorderStyleTypes` 常用：`0` NONE / `1` THIN / `8` MEDIUM / `7` DOUBLE 等。
+
+---
+
+## 5. 合并与冻结
+
+### 5.1 `mergeData`（`IRange[]`）
+
+```json
+{
+  "startRow": 0,
+  "startColumn": 0,
+  "endRow": 0,
+  "endColumn": 3
+}
+```
+
+| 参数 | 含义 |
+| ---- | ---- |
+| `startRow` / `endRow` | 起止行（含） |
+| `startColumn` / `endColumn` | 起止列（含） |
+| `rangeType` | 可选；普通合并可省略 |
+
+上例表示合并 `A1:D1`。
+
+### 5.2 `freeze`（`IFreeze`）
+
+| 参数 | 含义 |
+| ---- | ---- |
+| `xSplit` | 冻结列数 |
+| `ySplit` | 冻结行数 |
+| `startRow` | 可滚动区域起始行（常与冻结配合；无冻结可为 `-1`） |
+| `startColumn` | 可滚动区域起始列 |
+
+示例：冻结首行 → `"freeze": { "xSplit": 0, "ySplit": 1, "startRow": 1, "startColumn": 0 }`。
+
+---
+
+## 6. 行 / 列属性
+
+`rowData` / `columnData` 为稀疏对象，key 为行号 / 列号字符串。
+
+**行（`IRowData`）**
+
+| 参数 | 含义 |
+| ---- | ---- |
+| `h` | 行高（px） |
+| `hd` | 是否隐藏 |
+| `ia` | 是否自适应高度 |
+| `ah` | 自动行高值 |
+| `s` | 整行样式 id / 对象 |
+
+**列（`IColumnData`）**
+
+| 参数 | 含义 |
+| ---- | ---- |
+| `w` | 列宽（px） |
+| `hd` | 是否隐藏 |
+| `s` | 整列样式 |
+
+```json
+{
+  "rowData": { "0": { "h": 28 } },
+  "columnData": { "0": { "w": 120 }, "3": { "w": 100 } }
+}
+```
+
+---
+
+## 7. `resources`（插件状态）
+
+扩展能力（筛选、条件格式、数据验证、批注、超链接、绘图、表格对象、评论等）的运行时数据，多数写入根级 `resources`：
+
+```json
+{
+  "resources": [
+    {
+      "name": "SHEET_CONDITIONAL_FORMATTING_PLUGIN",
+      "data": "{...插件序列化 JSON 字符串...}"
+    }
+  ]
+}
+```
+
+| 参数 | 含义 |
+| ---- | ---- |
+| `name` | 插件资源名（形如 `SHEET_*_PLUGIN`） |
+| `data` | 序列化字符串（通常再 `JSON.parse`） |
+| `id` | 可选 |
+
+宿主做全量持久化时：**原样保存 `save()` 返回的 `resources`**，不要手改。xlsx 导入导出会丢弃这些字段。`features` 关闭的扩展不会加载对应预设，已有 `resources` 项可能无法还原 UI。
+
+---
+
+## 8. 本包精简结构（导入导出）
+
+与全量 `IWorkbookData` 相比，包内 `UniverWorkbookLike` / xlsx 转换保证：
+
+```ts
+{
+  id?: string;
+  name?: string;
+  sheetOrder?: string[];
+  styles?: Record<string, IStyleData | null>; // 导出时解析单元格 s 引用
+  sheets?: {
+    [id: string]: {
+      id?: string;
+      name?: string;
+      rowCount?: number;
+      columnCount?: number;
+      cellData?: Record<string, Record<string, { v?, f?, t?, s? }>>;
+      mergeData?: IRange[];
+    };
+  };
+}
+```
+
+| 能力 | 全量 `save()` | xlsx 导入导出（ExcelJS） |
+| ---- | ------------- | ------------- |
+| 值 / 公式 | ✅ | ✅ |
+| 基础样式（背景 / 字体 / 对齐） / 合并 | ✅ | ✅ |
+| 行列宽 / 边框 / 条件格式 / 图表 | ✅ | ❌ |
+| 插件 `resources` | ✅ | ❌ |
+
+生产建议：云端存 **`workbook.save()` JSON**；xlsx 仅作交换格式。
+
+---
+
+## 9. 宿主持久化示意
+
+```ts
+// 保存
+const snapshot = workbook.save();
+await api.putSheet(docId, snapshot);
+
+// 打开
+const snapshot = await api.getSheet(docId);
+api.createWorkbook(snapshot);
+```
+
+本包 `SheetEditor` 支持：
+
+| API | 说明 |
+| ---- | --- |
+| prop `workbook` | 初始快照；不传则 Demo 空表 |
+| prop `readOnly` | 只读（拦截命令 + pointer-events） |
+| `getSnapshot()` | `workbook.save()` 全量 JSON |
+| `loadSnapshot(data)` | 替换当前工作簿；不触发 `change`，完成后已保存 |
+| event `change` | 命令执行后防抖通知宿主（同时标脏） |
+| event `save` | Cmd/Ctrl+S：请求宿主落库；成功后调用 `markSaved()` |
+| `v-model:dirty` / `markSaved()` | 保存态；打开与 `loadSnapshot` 后默认已保存 |
+
+xlsx 导入导出仍可用，生产云存请优先快照 JSON。行数上限：`MAX_SHEET_ROW_COUNT = 10000`。
+
+可粘贴整本骨架：[`fixtures/sheet-workbook.template.json`](./fixtures/sheet-workbook.template.json)（含双 sheet、公式、样式引用、合并、冻结、行列宽）。
+
+---
+
+## 10. 类型索引（速查）
+
+| 层级 | 关键字段 | 章节 |
+| ---- | -------- | ---- |
+| 工作簿 | `id` `name` `appVersion` `locale` `styles` `sheetOrder` `sheets` `resources` | §1 |
+| 工作表 | `cellData` `mergeData` `rowData` `columnData` `freeze` `rowCount` `columnCount` | §2 |
+| 单元格 | `v` `t` `f` `s` | §3 |
+| 样式 | `bl` `it` `bg` `cl` `bd` `ht` `vt` `tb` `n` … | §4 |
+| 合并 / 冻结 | `mergeData[]` `freeze` | §5 |
+| 行列 | `h` `w` `hd` `s` | §6 |
+| 插件 | `resources[].name/data` | §7 |
+
+### 10.1 与运行时核对
+
+| 项 | 结果 |
+| --- | ---- |
+| 根类型 | 对齐 `@univerjs/core` `IWorkbookData` / `IWorksheetData` / `ICellData` |
+| Demo 初始 | `buildDemoWorkbook` 仅写 `id/name/sheetOrder/sheets.*.cellData` 等精简字段 |
+| xlsx | `exportWorkbookToXlsx` / `importWorkbookFromXlsx`（ExcelJS）值 / 公式 / 基础样式 / 合并 |
+| 不进快照契约的 | Univer UI 命令、容器 DOM、`features` 开关本身（开关影响能否还原 `resources`） |