XLSX 受控 editor

fsys.openXml.xlsx.editor 用于对既有普通 .xlsx 工作簿进行固定坐标的受控内容编辑。它只依赖公共 ZIP/关系层和系统 MSXML，不启动 Excel/WPS，不依赖 .NET，也不计算公式。

最小流程

import fsys.openXml.xlsx.editor;

var ed,err = fsys.openXml.xlsx.editor.open("/template.xlsx");
if(!ed) return null,err;

var cell,ce = ed.getCell("数据","B3");
var count,we,report = ed.setCell("数据","B3",{value="已完成"});
if(count===null) { ed.close(); return null,we; }

var output,se = ed.save("/filled.xlsx",{overwrite=true});
ed.close();
if(!output) return null,se;
return output,report;

源文件以只读会话打开，成功保存必须使用另一个 .xlsx 路径。默认不覆盖已有目标；即使指定 overwrite=true 也不能覆盖源文件或可识别的硬链接别名。

读取会话视图

var cell,err = ed.getCell("数据","B3");
var area,areaErr = ed.getRange("数据","A1:D10",{includeRows=true});

getCell 返回 ref/row/column/exists/hasValue/value/valueType/raw/styleIndex，以及 hasFormula/formula/formulaType/formulaRef/hasCachedValue 和 merge 等信息。公式的 value 只是文件保存的缓存；缓存失效或不存在时为 null，不伪造 0。

getRange 总是返回明确的 startRow/startColumn/endRow/endColumn/rowCount/columnCount 与稀疏 cells。includeRows=true 时附加 values/rows 矩阵，矩阵受 maxMatrixCells（默认 1000000）限制。合并区域不向非主格复制值，隐藏行列不被删除。

工作表选择器可以是 1 起序号、精确名称或 listSheets() 返回的描述对象。chartsheet/dialogsheet 可以列出，但不能作为单元格目标。地址只支持单格或矩形 A1，支持 $ 和小写，不支持整行、整列、多区域、工作表前缀或外部引用。

写入语义

单元格

ed.setCell("数据","B3",{value="文本"});
ed.setCell("数据","C3",{value=0});
ed.setCell("数据","D3",{value=false});
ed.setCell("数据","E3",{formula="SUM(C3,D3)"});
ed.setCell("数据","F3",{clear=true});

描述必须在 value/formula/clear 中选择一项：

空字符串、0、false 都是有效保存值；null 不是清除命令。
普通字符串（包括 =开头）按内联文本保存，不自动变成公式。
公式可以有一个前导 =，不写入调用者缓存；editor 不计算公式。
clear=true 删除值、公式和缓存，但保留 <c>、坐标、样式及工作表结构。
kind="date"/"datetime" 接受无时区 ISO 文本或 time 对象并写成 Excel 序列值；不自动创建或推断样式。kind="error" 只接受七种传统错误码。
未知字段、非法 UTF-8/XML 字符、超长文本、非有限数值和不支持的日期/错误值都会失败。

普通值或新公式覆盖已有公式默认拒绝：

var count,err = ed.setCell("数据","C3",{value=10},{allowFormulaOverwrite=true});

相同内容写入返回 0，不触发缓存失效。失败返回 null,err，此前已经成功的会话修改不回滚，但本次写入不提交。

矩形

var count,err,report = ed.setRange("数据","B3:D4",[
    [1,2,{formula="SUM(B3:C3)"}];
    [null,"",{clear=true}]
]);

values 必须是与 A1 矩形完全一致的二维数组；尾部空位使用显式 length 表达。null 跳过该位置，不改变内容和格式。任何位置越界、合并冲突、保护冲突、特殊公式或公式覆盖失败都会使整个 setRange 不提交。

合并区域只允许左上角主单元格，不能自动拆分或复制值。工作表坐标遵守 Excel 1 起边界：最大行 1048576、最大列 16384。

公式缓存失效

一次写操作真正改变单元格内容后，editor 对全工作簿执行保守失效：

保留所有公式 <f> 原文及其属性；
删除 <v>、非法公式缓存 <is> 和缓存类型属性，不填入 0/false/空串；
删除 calcChain.xml、工作簿关系中的 calcChain 关系以及 [Content_Types].xml 对应声明；
创建或更新 calcPr：calcMode="auto"、fullCalcOnLoad="1"、forceFullCalc="1"。

报告中的 formulaCount/clearedFormulaCacheCount/removedCalcChain/recalcRequested 只描述保存层操作。它不代表公式已经计算，也不代表图表、透视缓存、表对象计算列或外部链接结果已同步；需要最新结果请使用 Excel/WPS COM 打开、重算并保存。

拒绝范围

首版拒绝宏启用/旧格式/加密/签名包、工作簿保护、受保护目标工作表、共享/数组/数据表公式目标、表对象结构目标、插入删除行列、样式编辑以及复杂对象结构编辑。未知部件会保留，但涉及图表、透视、表对象或外链时报告 dependent-cache-not-updated 警告。

报告与原子性

setCell/setRange 的第一个返回值是实际发生内容变化的单元格数；报告还包含 changedCellCount/changedSheets/changedParts/formulaCount/clearedFormulaCacheCount/removedCalcChain/recalcRequested/warnings/sourcePath。save 报告另外包含 outputPath。

每个写操作先在独立 DOM 快照中完成全部检查，再通过公共 applyParts 一次提交；失败不会留下部分内存修改。保存使用公共 writer 的同目录临时 ZIP、完整关闭/CRC/限额检查和原子提交；失败不留下半成品，也不破坏已有目标。close() 直接丢弃尚未保存的内存修改。

Markdown 格式