API 参考 · lit-docx

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

读取

parseDocx

@quirekit/lit-docx

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

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

ParseOptions

@quirekit/lit-docx

`parseDocx` 接受的选项。

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

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

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

成员	说明
`ast`	LitAST 根节点，类型为 `document`；原样保留的部件、批注等包级数据位于 `ast.meta`。
`warnings`	非致命问题；触发问题的内容会尽量保留。

ParseWarning

@quirekit/lit-docx

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

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

成员	说明
`code`	稳定的代码，便于程序分类处理。
`message`	可读的问题说明。
`location`	问题所在的 XML 路径或位置描述。
`element`	触发警告的元素标签名。

DocxPackageError

@quirekit/lit-docx

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

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

生成

generateDocx

@quirekit/lit-docx

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

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