解析

本库提供两个层级的解析 API：

• parseDocument — 高层级往返 API，返回 DocumentOptions
• parseDocx — 对 .docx 文件原始 XML 部件的底层访问

两个函数均接受任意 DataType 输入：Uint8Array、ArrayBuffer、DataView、number[]、base64 字符串等。

往返（parseDocument）

parseDocument 函数将 .docx 文件解析为 DocumentOptions 格式，可直接传入 generateDocument() 重新导出，支持完整的往返流程（导出 → 解析 → 重新导出）：

import { parseDocument, generateDocument } from "@office-open/docx";
import { readFileSync } from "node:fs";

// 解析现有的 .docx 文件
const opts = parseDocument(readFileSync("input.docx"));

// 按需修改 sections，然后重新导出
const buffer = await generateDocument(opts);

返回的选项包含与输入格式相同的结构：

{
  "title": "我的文档",
  "creator": "作者",
  "sections": [
    {
      "children": [
        { "paragraph": "你好世界" },
        { "paragraph": { "children": [{ "text": "粗体", "bold": true }] } },
        { "table": { "rows": [...] } }
      ],
      "properties": { "page": { "margin": { ... } } }
    }
  ]
}

解析字段

支持的元素

解析器在往返中支持以下段落子元素：

| JSON 键 | 类型 | 描述 | | ------------------- | -------- | ---------------------------------------------------- | --- | | commentRangeStart | number | 批注范围起始标记 | | commentRangeEnd | number | 批注范围结束标记 | | commentReference | number | 批注定义引用 | | footnoteReference | number | 脚注引用（样式化） | | endnoteReference | number | 尾注引用（样式化） | | pageBreak | true | 分页符 | | columnBreak | true | 分栏符 | | symbolRun | object | 符号运行（Wingdings 等） | | math | object | 数学公式（OMML） | | chart | object | 图表（柱状、条形、折线、饼图） | | smartArt | object | SmartArt 图示 | | hyperlink | object | 超链接，包含 link、anchor、tooltip、children | | bookmarkStart | object | 书签起始，包含 id、name | | bookmarkEnd | number | 书签结束标记 | | image | object | 内嵌图片，包含 type、data、transformation | | object | object | 嵌入式 OLE 对象（w:object） | |

节级元素（段落、表格、目录、SDT、文本框、altChunk）均已完全支持。

底层解析（parseDocx）

parseDocx 函数读取 .docx 文件并提供对其原始 XML 部件的访问：

import { parseDocx } from "@office-open/docx";
import { readFileSync } from "node:fs";

const doc = parseDocx(readFileSync("input.docx"));

// 访问文档正文
console.log(doc.body);

// 访问样式（如果存在）
console.log(doc.styles);

// 访问编号（如果存在）
console.log(doc.numbering);

// 访问设置（如果存在）
console.log(doc.settings);

DocxDocument API

返回的 DocxDocument 对象包含以下内容：

访问部件

const doc = parseDocx(data);

// 按路径获取所有部件
const body = doc.doc.get("word/document.xml");
const styles = doc.doc.get("word/styles.xml");
const header = doc.doc.get(doc.partRefs.headers.get("rId1"));

// 部件引用将关系 ID 映射到路径
for (const [rId, path] of doc.partRefs.headers) {
  const header = doc.doc.get(path);
}

处理 XML 元素

已解析的元素使用 @office-open/xml 库的 Element 类型：

import { attr } from "@office-open/xml";

// 访问元素属性
const tagName = attr(doc.body, "tagName");

// 遍历子元素
for (const child of doc.body.elements ?? []) {
  console.log(child.name);
}

使用场景

• 往返 — 解析 .docx、修改节、重新导出
• 提取文本 — 遍历正文元素以提取段落文本
• 合并文档 — 解析多个 .docx 文件并合并其内容
• 检查格式 — 读取样式和编号定义
• 转换 — 修改已解析的元素并重建文档