离线 Office 编辑器

概述

C:/office 项目是一个单页、零后端的 Office 编辑器。三个编辑器（Excel 表格视图、Word 页面视图、PPT 幻灯片舞台）共享同一个 index.html 文件，以及按格式划分的独立引擎（excel.js、word.js、ppt.js）。构建流程会将所有依赖库与脚本内联进 office-standalone.html（约 5.7 MB），使其可直接双击运行——无需服务器、无需 CDN、无需网络连接。

难点不在于 UI 实现，而在于确保 Excel/Word/PPT 文件能正确往返转换（round-trip）。SheetJS（libs/xlsx.full.min.js）负责读写 ZIP/XML 格式，但会静默丢弃大量功能（条件格式、批注、数据验证、图表、样式、冻结窗格、超链接）。本项目的解决方案是引入一层 OOXML 后处理机制：SheetJS 生成基础文件，再由若干轻量级 injectXxx 函数重写特定 XML 片段（如 worksheet、rels、[Content_Types].xml），以补全 SheetJS 遗漏的内容；对应的反向 readXxx 函数则在打开文件时解析这些片段，并还原至 JS 数据结构中。该机制的行为一致性由基于 jsdom 的回归测试套件保障——它加载真实引擎并断言其行为。

何时使用此技能

• 用户要求为 C:/office 编辑器添加或修复任意功能。
• 任何需在 离线环境 下生成或编辑 .xlsx / .docx / .pptx 文件的任务，尤其包括： 条件格式（色阶、数据条、公式/单元格规则）、公式引擎（绝对引用、跨表引用、VLOOKUP/HLOOKUP/MATCH/INDEX/IFS）、单元格批注、数据验证、图表、超链接、冻结窗格、行列插入/删除、合并单元格、自定义样式。
• 编写或调试上述功能对应的 jsdom 回归测试。

核心架构（编辑前请务必阅读）

请始终维持统一的心智模型——该模型对所有功能均适用：

• 单一可信数据源 = 纯 JS 数据结构，而非 OOXML。 对于 Excel： data 是一个二维数组（ROWS × COLS）；其余所有信息均以并行 Map 或数组形式存储，键为 r + ',' + c（按单元格：如 styleMap、fmtMap、commentMap、borderMap、hyperlinks），或以区域范围/{r1,c1,r2,c2} 为键（如条件格式 cfRules、数据验证 dvRules、合并单元格）。Word/PPT 使用类似的 sheets[]/elements[] 结构。
• 编辑器从这些结构渲染界面（如 renderCell、renderAll）。文件格式仅是这些结构的 序列化结果，绝非原始数据源。
• 两个链式函数管控文件边界：
  • 保存：由 buildAndSaveBuffer() → 输出 Blob。功能逻辑实现在 injectXxx(zip, sheetsArr) 辅助函数中（参见 references/ooxml_paradigm.md）。
  • 打开：由 openWorkbook(buf) → 先通过 SheetJS 读取单元格值，再调用 readXxx(buf) 辅助函数，将被丢弃的功能恢复至 JS 结构中。
• 测试/调试钩子： window.__excelDeep 暴露了内部方法（如 setCellValue、getCfRules、addCfRule、cfMatchCell、renderAll、saveToBuffer、openWorkbook、evaluate 等）。jsdom 测试套件正是驱动这些接口，在无浏览器环境下验证真实引擎行为。

工作流：为 Excel 添加新功能

1. 建模。 将字段加入对应单元格的 Map，或加入 cfRules/dvRules/sheets[] 中。首先确定内存中的数据结构（例如，一条条件格式规则为 {r1,c1,r2,c2,type,...}）。
2. 渲染。 在 renderCell/renderAll 中实现（并在 styles.css 中添加必要 CSS）。文本内容必须始终位于覆盖层元素之上——为 .cell-input 设置 position:relative; z-index:1，覆盖层（如 cf-bar、标记等）则设更低 z-index 并启用 pointer-events:none。
3. 导出。 编写 injectXxx 函数重写对应 OOXML 片段，并将其接入 buildAndSaveBuffer 中正确的 CT_Worksheet 子节点顺序位置。
4. 导入。 编写 readXxx 函数解析同一 OOXML 片段，并接入 openWorkbook（需包裹在 try/catch 中——缺失部分不可导致打开失败）。
5. 暴露调试钩子。 在 window.__excelDeep 上挂载对应方法，供测试套件设置和读取状态。
6. 编写回归测试。 新建 _excel__test.js（参见 references/regression_harness.md 和 scripts/regression_harness.js）。
7. 重新构建 + 冒烟测试： 运行 node build-standalone.js，再执行 _standalone_smoke.js，确认无加载时错误（0 errors）。

OOXML inject/read 范式（最易被忽视的核心）

这是最具复用价值的知识点。完整代码模式、buffer 类型规则、[Content_Types].xml 覆盖机制、rels 关联方式，以及一个带注释的条件格式示例，全部详述于 references/ooxml_paradigm.md。在编写任意 injectXxx/readXxx 函数前，请务必通读该文档。关键规则（不可跳过）：

• 注入器（injector）接收一个 JSZip 实例，返回一个 arraybuffer（不是 Blob），以便下一个注入器可通过 JSZip.loadAsync 加载。仅最终的 buildAndSaveBuffer 会将最后一个 buffer 包裹为 new Blob([out])。
• 往返传输公式或任何含 <、>、&、" 的文本时（例如条件格式公式中的 >A1>10<），必须成对使用 escapeXml 与 unescapeXml。
• 内存模型类型名必须与 OOXML 类型名严格区分。 示例：内存中条件格式规则使用 type:'scale'|'bar'|'formula'，而 OOXML 中对应为 。双向映射必须准确；若不匹配，规则将在保存时被静默丢弃。
• 调用 XLSX.write(..., {cellStyles:true}) 后，再对返回的 arraybuffer 执行 JSZip.loadAsync。

jsdom 回归测试套件

每个功能均配套一个回归测试：该测试在 jsdom 中加载真实引擎并断言其行为（包括完整的“保存→重新打开”往返流程）。模板、精确的 NODE_PATH 配置、jsdom ^24 版本锁定，以及两个经典陷阱（setTimeout 中未 await 异步操作；|| -1 将合法的 0 错误转为 -1）详见 references/regression_harness.md，以及开箱即用的 scripts/regression_harness.js。

参考资料

• references/ooxml_paradigm.md —— save/read 链路、buffer 类型、Content_Types 覆盖、rels 关联、带注释的条件格式与批注示例。
• references/regression_harness.md —— jsdom 测试套件模板、环境配置、常见陷阱说明。
• scripts/regression_harness.js —— 可直接复制粘贴的新测试骨架文件。