aardio 文档

fsys.openXml：Office Open XML 文件处理基础库

fsys.openXml 以读取与分析优先，按需扩展受控编辑与生成为定位。当前提供共享 ZIP 部件、内容类型、关系及媒体导出；fsys.openXml.pptx/docx/xlsx 提供对应格式的高层读取入口。

0.7.0 增加 PPTX 渐变与透明度、图片等比适配/裁切、段落间距和样式表格。 完整 6 页示例见 ~/examples/File/OpenXML/pptx-design.aardio。

0.8.0 增加生成前版式预检 builder.check（文字溢出、表格被撑高、超出页面、文字重叠，不需要 Office），并支持中英文分设字体、语言标签、备注独立字号、虚线与箭头、两点画线；同一图片只嵌入一份，生成错误带页号与形状名。详见 PPTX 生成与预检。

0.6.0 新增 PPTX 生成、常用动画与有限编辑另存。 保持原有 open/read 只读；不以完整 Office 编辑器、排版渲染引擎或 OPC/XSD 校验器为目标。生成与编辑见 PPTX 生成、PPTX 有限编辑。

0.2.0 起 XML 后端使用 web.msxml（Windows 系统 MSXML COM 组件），ZIP 读取复用 zlib；不需要 Office、WPS、.NET 或其他语言运行时。0.5.0 新增 XLSX 基础读取与 Excel 技能兼容接入，PPTX/DOCX/XLSX 共用媒体导出。 读取不创建临时解压目录；仅显式导出才写入目标文件，不修改源包。

0.5.1 起 ZIP 层完全由标准库 zlib.unzip 对象提供：zlib.unzip(path,false) 只读模式打开、eachFile/getPos/setPos 建立随机访问索引、readCurrentFile 整读并校验长度与 CRC。本库不再声明或调用任何 zlib 底层 API，ZIP 相关能力如需增强应在 zlib.unzip 中补充，而不是在这里重复封装。

0.9.0 支持逐段落动画、Morph 与兼容淡出回退、标题占位符/标准版式。0.10.0 新增页码字段、点击超链接、原生编号列表、外阴影与可控圆角；详见 页码与交互细节，演示见 ~/examples/File/OpenXML/pptx-details.aardio。这些新增能力仍优先由原生生成器完成。

0.11.0 新增同文稿复制/删除幻灯片、保留格式的表格填值与矩形合并，详见 模板与数据。复制已有常见图表时，图表与内嵌工作簿独立克隆；用户母版导入与近似预览暂未实现。

0.12.0 新增二维柱状/条形/折线/饼图的小范围原生生成，每图有独立内嵌XLSX，分类、系列、数值引用与缓存一致，0/null严格区分。见 二维原生图表 与 ~/examples/File/OpenXML/pptx-charts.aardio。不等于已支持任意图表编辑；XLSX打包能力仅供嵌入数据使用，不是完整Excel写入引擎。

0.12.1 修复 WPS 导入表格时边距归零及垂直对齐被覆盖的问题：表格单元格的边距与对齐只写入 tcPr，内部 bodyPr 不再重复声明。普通文字、备注与预检计算不变；已有旧文件不会被自动迁移，重新运行生成示例即可得到修正版。详见 PPTX 生成。

Word 结构化生成：fsys.openXml.docx.builder 生成段落/标题、格式化运行、普通及嵌套表格、编号、书签和超链接，使用公共 writer 完成写包。string.html.toDocx 只保留 Markdown 所需 HTML 语义适配，复用该生成器。见 Word 生成指南 与 ~/examples/File/OpenXML/docx-write.aardio；这是新建 DOCX 的有限子集，不是既有 Word 文档编辑器。

模块与依赖

后续编辑与生成按需组合基础模块和 ZIP 读写模块，不要求纯生成器为了复用公共代码而加载 ZIP 读取器。现有 open/read 系列接口保持不修改源件；新增写入使用明确的写入或另存接口。

读取 PPTX

import fsys.openXml.pptx;
var data,err = fsys.openXml.pptx.read("/input.pptx");
if(!data) return null,err;

for i,text in data.slides {
    print("第 " + i + " 页",text);
}
return data;

页面顺序由主文档确定，不按 ZIP 枚举顺序或文件编号排序。详见 PPTX 文本读取。

读取 DOCX

import fsys.openXml.docx;
var data,err = fsys.openXml.docx.read("/input.docx");
if(!data) return null,err;
print(data.text);
return data;

保留段落/单元格边界，按真实关系定位主文档及请求的附属部件，不依赖固定 w: 前缀。输出是普通数据，不是页面渲染；内容截取通过 truncated/warnings 报告。详见 DOCX 内容读取与媒体。

读取包内文件

import fsys.openXml;
var pkg,err = fsys.openXml.open("/input.pptx");
if(!pkg) return null,err;

var mainPart,err = pkg.getMainPart();
if(!mainPart){ pkg.close(); return null,err; }

var root,err = pkg.readXml(mainPart);
var parts = pkg.listParts();
pkg.close();
if(!root) return null,err;

print("主文档",mainPart,root.tagName);
return parts;

原始部件导出约定

XML 查询约定

readXml() 返回 MSXML DOM 的根元素 COM 对象，不再是 string.xml 表节点。使用 fsys.openXml.xml.isElement/child/children/attribute/text 按命名空间 URI 与本地名精确查询，避免依赖 p:、a: 等固定前缀。属性通过 attribute() 读取，实体只解码一次。

MSXML 负责 XML 解码及良构性检查，支持 UTF-8、带 BOM 的 UTF-16 LE/BE 和 Unicode XML 名称。禁用 DTD、外部实体和加载时验证，不调用 Office/WPS，不做 XSD 或完整 OPC 验证。MSXML6 显式启用新解析器和属性空白规范化；具体文本换行规则与 XP 降级限制见 XML 查询辅助。

DOM 节点只在创建它的线程内使用，关闭 ZIP 包后仍可查询。不要将它们作为普通表序列化或跨线程传递；需要跨线程结果时先提取字符串/数组，或使用返回普通数据的 pptx.read()、docx.read() 或 xlsx.readSheet/readWorkbook()。DOM 本身可以在内存中修改，但这些修改不会自动写回 ZIP 包。显式提交 DOM 可用 editor.setXml/save；修改后的 XML 不承诺逐字节往返一致，未修改部件则保留原始解压字节。

限额与失败

open(path,options) 及 PPTX/DOCX/XLSX 高层入口的 options 均支持以下安全限额。DOCX/XLSX 另有内容输出选择及矩形/文本展开限制，见各自指南；不要混为同一种限额：

参数 默认值 含义
maxEntries 10000 中央目录条目数，包含目录
maxPartBytes 16777216 单个被读取部件的解压字节数，16 MiB
maxReadBytes 134217728 一个包累计读取字节数，128 MiB，重复读取也累计
maxXmlDepth 128 单个 XML 最大元素深度；MSXML6 在解析时限制，解析后再检查
maxXmlNodes 200000 DOM 解析后的节点计数，包含元素、文本、CDATA、注释、处理指令，不含文档节点本身及属性

限额必须是正整数；超限返回错误而不截断结果。节点数限制在 DOM 创建后检查，不是解析前的内存上限；包层同时限制 XML 部件字节数。按需读取意味着未读取的媒体等部件不会做 CRC 或内容校验，不能把成功提取文本当成整份文件通过全面校验。

传统二进制 .doc/.xls/.ppt、加密 Office 文件、加密/分卷 ZIP 不在支持范围。不会执行宏、嵌入对象或外部关系。不静默将损坏包、缺件或不支持的文档当成空结果。

Markdown 格式