# API 参考

读取与生成 DOCX 用到的公开函数、类型与错误，签名从源码生成。

以下签名与说明从 `@quirekit/lit-docx` 的公开入口自动提取。LitAST 节点类型见 [LitAST 节点模型](/guide/litast)。

## 读取

### parseDocx

`@quirekit/lit-docx` · Commercial

把 DOCX 字节解析为 LitAST。可在浏览器与 Node 中运行，不需要访问文件系统。
@param buffer - 完整 DOCX 文件的字节。
@param options - 可选的解析行为。
@returns 文档树与非致命警告。
@throws DocxPackageError：字节不是 ZIP 包，或是 OLE 容器（如加密文档、旧版 `.doc`）。

```ts
function parseDocx(buffer: Uint8Array, options?: ParseOptions): Promise<ParseResult>
```

### ParseOptions

`@quirekit/lit-docx` · Commercial

`parseDocx` 接受的选项。

```ts
interface ParseOptions {
    preserveRawXml?: boolean;
    plugins?: ParserPlugin[];
    chartSourceLimits?: ChartSourceLimits;
    numberingMode?: NumberingParseMode;
    malformedFieldMode?: 'best-effort' | 'strict';
}
```

**preserveRawXml** — 把无法识别的元素保留为 `unknownBlock` / `unknownInline` 节点，原始 XML 存在 `rawXml` 中；只有显式传 `false` 才会丢弃。

**plugins** — 额外的解析插件，在内置插件之后参与匹配。

**chartSourceLimits** — 图表源数据的体积上限；超出时拒绝导入。

**numberingMode** — 编号的重建方式：`list` / `listItem` 节点（默认），或 Word 式的扁平编号段落。

**malformedFieldMode** — 遇到格式错误的复杂域时，保留内容并给出警告（`best-effort`，默认），或拒绝当前文本流（`strict`）。

### ParseResult

`@quirekit/lit-docx` · Commercial

`parseDocx` 的结果：文档树，以及读取过程中发现的所有非致命问题。

```ts
interface ParseResult {
    ast: LitNode;
    warnings: ParseWarning[];
}
```

**ast** — LitAST 根节点，类型为 `document`；原样保留的部件、批注等包级数据位于 `ast.meta`。

**warnings** — 非致命问题；触发问题的内容会尽量保留。

### ParseWarning

`@quirekit/lit-docx` · Commercial

解析时发现的一个非致命问题。

```ts
interface ParseWarning {
    code: string;
    message: string;
    location?: string;
    element?: string;
}
```

**code** — 稳定的代码，便于程序分类处理。

**message** — 可读的问题说明。

**location** — 问题所在的 XML 路径或位置描述。

**element** — 触发警告的元素标签名。

### DocxPackageError

`@quirekit/lit-docx` · Commercial

在开始解析文档内容之前抛出的包级错误，用 `code` 区分原因。

```ts
export class DocxPackageError extends Error {
    readonly code: DocxPackageErrorCode;
    constructor(code: DocxPackageErrorCode, message: string, options?: ErrorOptions);
}
```

## 生成

### generateDocx

`@quirekit/lit-docx` · Commercial

从 LitAST 生成完整的 DOCX 文件，整个包都根据文档树重建。可在浏览器与 Node 中运行。
@param ast - 文档树的根节点。
@returns 完整 DOCX（ZIP）文件的字节。

```ts
function generateDocx(ast: LitAstNode): Promise<Uint8Array<ArrayBuffer>>
```