# fsys.openXml.xml：XML 解析与查询辅助

通常先使用 `pkg.readXml(partName)`；直接解析字节串时可用 `parse`。0.2.0 起返回 MSXML DOM 根元素 COM 对象，由 `web.msxml` 创建；不再返回 `string.xml` 表节点，也没有额外的自建 Office 类型系统。

本模块可单独导入，不加载包读取入口或 `zlib.unzip`。当前提供解析与查询辅助；返回的 DOM 本身可以在内存中修改，并非只读节点，但修改不会自动保存到源文件。

```aardio
import fsys.openXml.xml;
var x = fsys.openXml.xml;
var root,err = x.parse(`<s:root xmlns:s="urn:sample" xmlns:r="urn:rels" r:id="a&amp;b"><s:title>  中文 &amp; text  </s:title></s:root>`);
if(!root) return null,err;

var title = x.child(root,"urn:sample","title");
print(x.attribute(root,"id","urn:rels")); // a&b
return x.text(title); // 保留首尾两个空格
```

- `isElement(node,uri,name)`：大小写敏感，按命名空间 URI 和本地名匹配。
- `child/children(node,uri,name)`：首个 / 全部匹配的直接子元素，保持源顺序。
- `attribute(node,name,uri="")`：属性实体只解码一次；省略 URI 表示无命名空间属性。XML 默认命名空间不作用于无前缀属性。
- `text(node)`：拼接文本和 CDATA，不自行插入段落或表格分隔符。

标签前缀可以变化、包含点号或使用默认命名空间；名称、属性和文本由 MSXML 处理，支持 Unicode XML 名称。`children(node)` 返回所有直接子元素的 aardio 数组；`uri` 或 `name` 为 null 时不限制相应条件。数组内仍是 COM 节点，不可跨线程传递。空属性返回空字符串，缺失属性返回 null；`text(null)` 返回空字符串。

## 空白与兼容差异

- `preserveWhiteSpace=true` 保留首尾空格和空白文本节点；`text()` 拼接文本与 CDATA，不包含注释和处理指令。
- 在本机 MSXML6 实测中，文本节点的 CR/CRLF（**包括数字字符引用表示的 CR**）会归一化为 LF。这是相对于 0.1.0 的已知差异，不承诺 XML 原始字节往返一致。
- MSXML6 启用 `NewParser=true` 与 `NormalizeAttributeValues=true`；属性中的物理 CR/CRLF/TAB/LF 规范化为空格，属性字符引用表示的 CR/LF/TAB 保留。
- 名称、命名空间和重复属性检查由 MSXML6 新解析器处理；不做 XSD 校验。

## 输入、安全与生命周期

`parse(data,options)` 接受非空 string/buffer 字节串，通过字节 SAFEARRAY 调用 DOM `load`，不把输入当文件路径或网址。BOM 与编码声明由 MSXML 识别；已测试 UTF-8、UTF-16 LE/BE。失败返回 `null,err`，解析错误含行列和原因；不静默修补坏 XML。

禁用 DTD、外部实体和加载时验证，不执行处理指令，不读取外部 URL/文件；不是完整 OPC/XSD/Markup Compatibility 验证器。`options.maxXmlDepth/maxXmlNodes` 默认分别为 128/200000，最大允许 256/2000000。MSXML6 在解析时限制深度；节点数在 DOM 创建后检查，包含注释和处理指令，不含文档节点本身及属性。直接调用 `parse` 的调用方应自行限制输入字节数；包层已经有部件字节限额。

`web.msxml` 在 Windows XP 上退化为 MSXML3；仅在非 XP 启用上述 MSXML6 专用属性。**XP/MSXML3 路径尚未验证**，新解析器、属性规范化及解析时深度限制不适用于此降级路径，不承诺与 MSXML6 完全相同的结果。

DOM 节点仅在创建线程内使用；关闭 ZIP 包后仍可读取。提取为普通字符串/数组以后再跨线程传值，避免把 COM 节点交给 JSON 或线程序列化器。当前版本尚未提供将 DOM 修改写回包的接口，不承诺原始 XML 字节往返一致；后续可按实际需求增加受控编辑与保存能力。关于包和安全边界，见 [包层说明](../index.html)。