Mammoth.js 中处理 Word 列表转换的技术解析

2025-06-07 08:29:33作者：田桥桑Industrious

在文档处理领域，将 Word 文档转换为 HTML 是一个常见需求。Mammoth.js 作为一个优秀的文档转换库，在实际应用中可能会遇到一些特殊情况。本文将深入分析一个关于列表转换的典型案例，探讨其技术原理和解决方案。

问题现象

当使用 Mammoth.js 转换包含格式化列表的 Word 文档时，开发者发现有序列表和无序列表都被转换成了普通段落，而不是预期的 <ol> 或 <ul> HTML 标签。具体表现为转换结果如下：

<p style="text-align: left">Part I</p>
<p style="text-align: left">Part II</p>

根本原因分析

经过深入排查，发现问题并非源于 Mammoth.js 本身，而是与开发者自定义的转换逻辑有关。关键点在于：

Word 文档结构特性：在 Word 文档中，所有列表项本质上都是带有特殊属性的段落元素，而非独立的列表类型。
自定义转换函数干扰：开发者为了实现文本对齐功能，添加了 transformDocument 选项，其中包含了对段落元素的特殊处理逻辑。
样式名称判断不足：原始代码通过样式名称中包含 "list" 来判断是否为列表项，但实际文档可能使用其他样式名称（如 "standard locker"）。

解决方案

针对这一问题，我们推荐以下几种解决方案：

方案一：利用样式映射优先级

通过调整样式映射的顺序，确保列表相关的样式映射优先于普通段落样式：

const options = {
    styleMap: [
        "p[style-name='List Paragraph'] => li:fresh",
        // 其他样式映射...
    ]
}

方案二：完善转换函数逻辑

更可靠的方法是检查元素的 numbering 属性，这是 Word 文档中标识列表项的核心属性：

const transformElement = element => {
    if (element.children) {
        const children = element.children.map(transformElement);
        element = {...element, children: children};
    }

    if (element.type === "paragraph" && !element.numbering) {
        element = transformParagraph(element);
    }
    return element;
}

方案三：结合两种方法

最稳健的方案是同时使用样式映射和转换函数，既处理显式设置的列表项，也处理通过样式应用的列表项：

const options = {
    styleMap: [
        "p[style-name='List Paragraph'] => li:fresh",
        // 其他列表样式...
    ],
    transformDocument: transformElement
}