Mammoth .docx 到 HTML 转换器

Mammoth 旨在将 .docx 文档(如 Microsoft Word、Google Docs 和 LibreOffice 创建的文档)转换为 HTML。Mammoth 通过使用文档中的语义信息并忽略其他细节，力求生成简单清晰的 HTML。例如，Mammoth 将任何使用"标题 1"样式的段落转换为 h1 元素，而不是试图精确复制标题的样式(字体、文本大小、颜色等)。

.docx 和 HTML 的结构存在较大差异，这意味着对于较复杂的文档，转换可能无法做到完美。如果你只使用样式来语义化标记文档，Mammoth 的效果最佳。

目前支持以下功能:

• 标题

• 列表

• 可自定义从 docx 样式到 HTML 的映射。 例如，通过提供适当的样式映射，你可以将 WarningHeading 转换为 h1.warning。

• 表格 目前忽略表格本身的格式(如边框)， 但文本的格式处理与文档其他部分相同。

• 脚注和尾注

• 图片

• 粗体、斜体、下划线、删除线、上标和下标

• 链接

• 换行

• 文本框。文本框的内容被视为单独的段落， 出现在包含文本框的段落之后。

• 注释

Web 演示

尝试 Mammoth 最简单的方法是使用 Web 演示:

• 克隆此仓库
• 运行 make setup
• 在 Web 浏览器中打开 browser-demo/index.html

安装

npm install mammoth

其他支持的平台

• Python 可在 PyPI 上获取。

• WordPress

• Java/JVM 可在 Maven Central 上获取。

• .NET 可在 NuGet 上获取。

使用方法

命令行界面

你可以通过传递 docx 文件路径和输出文件来转换 docx 文件。 例如:

mammoth document.docx output.html

如果未指定输出文件，输出将写入标准输出。

输出是一个 HTML 片段，而不是完整的 HTML 文档，使用 UTF-8 编码。 由于片段中未明确设置编码， 如果浏览器默认不使用 UTF-8，在 Web 浏览器中打开输出文件可能会导致 Unicode 字符显示不正确。

图片

默认情况下，图片会内联包含在输出的 HTML 中。 如果通过 --output-dir 指定了输出目录， 图片将被写入单独的文件。 例如:

mammoth document.docx --output-dir=output-dir

如果存在现有文件，将被覆盖。

样式

可以使用 --style-map 从文件中读取自定义样式映射。 例如:

mammoth document.docx output.html --style-map=custom-style-map

其中 custom-style-map 看起来像这样:

p[style-name='Aside Heading'] => div.aside > h2:fresh
p[style-name='Aside Text'] => div.aside > p:fresh

样式映射的语法说明可以在"编写样式映射"部分找到。

Markdown

Markdown 支持已被弃用。 建议生成 HTML 并使用单独的库将 HTML 转换为 Markdown， 这可能会产生更好的结果。

使用 --output-format=markdown 将生成 Markdown。 例如:

mammoth document.docx --output-format=markdown

库

在 Node.js 和浏览器中，可以通过常规方式引入 Mammoth:

var mammoth = require("mammoth");

另外，你也可以使用独立的 JavaScript 文件 mammoth.browser.js， 它包含了 Mammoth 及其依赖项。 这个文件使用任何已加载的模块系统。 例如，当使用 CommonJS 时:

var mammoth = require("mammoth/mammoth.browser");

如果没有找到模块系统， mammoth 将被设置为全局窗口变量。

在开发过程中可以使用 make setup 生成该文件。

基本转换

要将现有的 .docx 文件转换为 HTML，请使用 mammoth.convertToHtml:

var mammoth = require("mammoth");

mammoth.convertToHtml({path: "path/to/document.docx"})
    .then(function(result){
        var html = result.value; // 生成的 HTML
        var messages = result.messages; // 任何消息，如转换过程中的警告
    })
    .catch(function(error) {
        console.error(error);
    });

注意 mammoth.convertToHtml 返回一个 promise。

你也可以使用 mammoth.extractRawText 提取文档的原始文本。 这将忽略文档中的所有格式。 每个段落后面跟两个换行符。

mammoth.extractRawText({path: "path/to/document.docx"})
    .then(function(result){
        var text = result.value; // 原始文本
        var messages = result.messages;
    })
    .catch(function(error) {
        console.error(error);
    });

自定义样式映射

默认情况下， Mammoth 将一些常见的 .docx 样式映射到 HTML 元素。 例如， 样式名为 Heading 1 的段落被转换为 h1 元素。 你可以通过将一个带有 styleMap 属性的选项对象作为第二个参数传递给 convertToHtml 来传入自定义样式映射。 样式映射的语法说明可以在"编写样式映射"部分找到。 例如，如果样式名为 Section Title 的段落应转换为 h1 元素， 样式名为 Subsection Title 的段落应转换为 h2 元素:

var mammoth = require("mammoth");

var options = {
    styleMap: [
        "p[style-name='Section Title'] => h1:fresh",
        "p[style-name='Subsection Title'] => h2:fresh"
    ]
};
mammoth.convertToHtml({path: "path/to/document.docx"}, options);

为了更方便地支持存储在文本文件中的样式映射， styleMap 也可以是字符串。 每行被视为单独的样式映射， 忽略空行和以 # 开头的行:

var options = {
    styleMap: "p[style-name='Section Title'] => h1:fresh\n" +
        "p[style-name='Subsection Title'] => h2:fresh"
};

用户定义的样式映射优先于默认样式映射。 要完全停用默认样式映射， 将 options.includeDefaultStyleMap 设置为 false:

var options = {
    styleMap: [
        "p[style-name='Section Title'] => h1:fresh",
        "p[style-name='Subsection Title'] => h2:fresh"
    ],
    includeDefaultStyleMap: false
};

自定义图片处理器

默认情况下，图片被转换为 <img> 元素，源内联包含在 src 属性中。 可以通过将 convertImage 选项设置为图片转换器来更改此行为。

例如，以下代码将复制默认行为:

var options = {
    convertImage: mammoth.images.imgElement(function(image) {
        return image.read("base64").then(function(imageBuffer) {
            return {
                src: "data:" + image.contentType + ";base64," + imageBuffer
            };
        });
    })
};

粗体

默认情况下，粗体文本被包裹在<strong>标签中。 可以通过为b添加样式映射来改变这个行为。 例如，要将粗体文本包裹在<em>标签中：

var mammoth = require("mammoth");

var options = {
    styleMap: [
        "b => em"
    ]
};
mammoth.convertToHtml({path: "path/to/document.docx"}, options);

斜体

默认情况下，斜体文本被包裹在<em>标签中。 可以通过为i添加样式映射来改变这个行为。 例如，要将斜体文本包裹在<strong>标签中：

var mammoth = require("mammoth");

var options = {
    styleMap: [
        "i => strong"
    ]
};
mammoth.convertToHtml({path: "path/to/document.docx"}, options);

下划线

默认情况下，任何文本的下划线都会被忽略，因为在HTML文档中下划线可能会与链接混淆。 可以通过为u添加样式映射来改变这个行为。 例如，假设源文档使用下划线来强调。 以下代码会将任何明确带有下划线的源文本包裹在<em>标签中：

var mammoth = require("mammoth");

var options = {
    styleMap: [
        "u => em"
    ]
};
mammoth.convertToHtml({path: "path/to/document.docx"}, options);

删除线

默认情况下，删除线文本被包裹在<s>标签中。 可以通过为strike添加样式映射来改变这个行为。 例如，要将删除线文本包裹在<del>标签中：

var mammoth = require("mammoth");

var options = {
    styleMap: [
        "strike => del"
    ]
};
mammoth.convertToHtml({path: "path/to/document.docx"}, options);

注释

默认情况下，注释会被忽略。 要在生成的HTML中包含注释， 为comment-reference添加样式映射。 例如：

var mammoth = require("mammoth");

var options = {
    styleMap: [
        "comment-reference => sup"
    ]
};
mammoth.convertToHtml({path: "path/to/document.docx"}, options);

注释将被附加到文档末尾， 指向注释的链接将使用指定的样式映射进行包裹。

API

mammoth.convertToHtml(input, options)

将源文档转换为HTML。

• input：描述源文档的对象。 在node.js上，支持以下输入：

  • {path: path}，其中path是.docx文件的路径。
  • {buffer: buffer}，其中buffer是包含.docx文件的node.js Buffer。

  在浏览器中，支持以下输入：

  • {arrayBuffer: arrayBuffer}，其中arrayBuffer是包含.docx文件的数组缓冲区。

• options（可选）：转换的选项。 可能包含以下属性：

  • styleMap：控制Word样式到HTML的映射。 如果options.styleMap是一个字符串， 每行被视为一个单独的样式映射， 忽略空行和以#开头的行： 如果options.styleMap是一个数组， 每个元素应该是一个代表单个样式映射的字符串。 有关样式映射语法的参考，请参见"编写样式映射"。

  • includeEmbeddedStyleMap：默认情况下， 如果文档包含嵌入的样式映射，则它会与默认样式映射组合。 要忽略任何嵌入的样式映射， 将options.includeEmbeddedStyleMap设置为false。

  • includeDefaultStyleMap：默认情况下， 在styleMap中传递的样式映射与默认样式映射组合。 要完全停止使用默认样式映射， 将options.includeDefaultStyleMap设置为false。

  • convertImage：默认情况下，图像被转换为<img>元素，源内容内联包含在src属性中。 将此选项设置为图像转换器以覆盖默认行为。

  • ignoreEmptyParagraphs：默认情况下，空段落会被忽略。 将此选项设置为false以在输出中保留空段落。

  • idPrefix： 一个字符串，用于在任何生成的ID前添加前缀， 如书签、脚注和尾注使用的ID。 默认为空字符串。

  • transformDocument：如果设置， 这个函数会在从docx文件读取文档后，转换为HTML之前应用于文档。 文档转换的API应该被视为不稳定的。 参见文档转换。

• 返回一个包含结果的promise。 这个结果有以下属性：

  • value：生成的HTML

  • messages：转换过程中生成的任何消息，如错误和警告

mammoth.convertToMarkdown(input, options)

Markdown支持已被弃用。 建议生成HTML并使用单独的库将HTML转换为Markdown， 这可能会产生更好的结果。

将源文档转换为Markdown。 这与convertToHtml的行为相同， 只是结果的value属性包含Markdown而不是HTML。

mammoth.extractRawText(input)

提取文档的原始文本。 这将忽略文档中的所有格式。 每个段落后面跟两个换行符。

• input：描述源文档的对象。 在node.js上，支持以下输入：

  • {path: path}，其中path是.docx文件的路径。
  • {buffer: buffer}，其中buffer是包含.docx文件的node.js Buffer。

  在浏览器中，支持以下输入：

  • {arrayBuffer: arrayBuffer}，其中arrayBuffer是包含.docx文件的数组缓冲区。

• 返回一个包含结果的promise。 这个结果有以下属性：

  • value：原始文本

  • messages：任何消息，如错误和警告

mammoth.embedStyleMap(input, styleMap)

给定一个现有的docx文件， embedStyleMap将生成一个新的docx文件，其中嵌入了传递的样式映射。 当Mammoth读取新的docx文件时， 它将使用嵌入的样式映射。

• input：描述源文档的对象。 在node.js上，支持以下输入：

  • {path: path}，其中path是.docx文件的路径。
  • {buffer: buffer}，其中buffer是包含.docx文件的node.js Buffer。

  在浏览器中，支持以下输入：

  • {arrayBuffer: arrayBuffer}，其中arrayBuffer是包含.docx文件的数组缓冲区。

• styleMap：要嵌入的样式映射。

• 返回一个promise。 在promise内部的值上调用toArrayBuffer()以获取表示新文档的ArrayBuffer。 在promise内部的值上调用toBuffer()以获取表示新文档的Buffer。

例如：

mammoth.embedStyleMap({path: sourcePath}, "p[style-name='Section Title'] => h1:fresh")
    .then(function(docx) {
        fs.writeFile(destinationPath, docx.toBuffer(), callback);
    });

消息

每条消息都有以下属性：

• type：表示消息类型的字符串，如"warning"或"error"

• message：包含实际消息的字符串

• error（可选）：导致此消息的抛出异常（如果有的话）

图像转换器

可以通过调用 mammoth.images.imgElement(func) 来创建图像转换器。 这会为原始 docx 中的每个图像创建一个 <img> 元素。 func 应该是一个接受一个参数 image 的函数。 这个参数是正在转换的图像元素，具有以下属性：

• contentType：图像的内容类型，如 image/png。

• readAsArrayBuffer()：将图像文件读取为 ArrayBuffer。 返回一个 ArrayBuffer 的 promise。

• readAsBuffer()：将图像文件读取为 Buffer。 返回一个 Buffer 的 promise。 除非使用了 Buffer 的 polyfill，否则在浏览器中不支持此功能。

• readAsBase64String()：将图像文件读取为 base64 编码的字符串。 返回一个 string 的 promise。

• read([encoding]) (已废弃)：以指定的编码读取图像文件。 如果指定了编码，则返回一个 string 的 promise。 如果未指定编码，则返回一个 Buffer 的 promise。

func 应返回一个对象（或对象的 promise），包含 <img> 元素的属性。 至少应包含 src 属性。 如果找到图像的任何替代文本， 将自动添加到元素的属性中。

例如，以下代码复制了默认的图像转换：

mammoth.images.imgElement(function(image) {
    return image.readAsBase64String().then(function(imageBuffer) {
        return {
            src: "data:" + image.contentType + ";base64," + imageBuffer
        };
    });
})

mammoth.images.dataUri 是默认的图像转换器。

文档转换

文档转换的 API 应被视为不稳定， 可能在任何版本之间发生变化。 如果你依赖此行为， 应该固定使用特定版本的 mammoth.js， 并在更新前仔细测试。

Mammoth 允许在转换文档之前对其进行转换。 例如， 假设文档没有进行语义标记， 但你知道任何居中对齐的段落都应该是标题。 你可以使用 transformDocument 参数来适当修改文档：

function transformElement(element) {
    if (element.children) {
        var children = _.map(element.children, transformElement);
        element = {...element, children: children};
    }

    if (element.type === "paragraph") {
        element = transformParagraph(element);
    }

    return element;
}

function transformParagraph(element) {
    if (element.alignment === "center" && !element.styleId) {
        return {...element, styleId: "Heading2"};
    } else {
        return element;
    }
}

var options = {
    transformDocument: transformElement
};

transformDocument 的返回值在生成 HTML 时使用。

上述代码可以使用辅助函数 mammoth.transforms.paragraph 更简洁地编写：

function transformParagraph(element) {
    if (element.alignment === "center" && !element.styleId) {
        return {...element, styleId: "Heading2"};
    } else {
        return element;
    }
}

var options = {
    transformDocument: mammoth.transforms.paragraph(transformParagraph)
};

或者，如果你希望将明确设置为使用等宽字体的段落表示为代码：

const monospaceFonts = ["consolas", "courier", "courier new"];

function transformParagraph(paragraph) {
    var runs = mammoth.transforms.getDescendantsOfType(paragraph, "run");
    var isMatch = runs.length > 0 && runs.every(function(run) {
        return run.font && monospaceFonts.indexOf(run.font.toLowerCase()) !== -1;
    });
    if (isMatch) {
        return {
            ...paragraph,
            styleId: "code",
            styleName: "Code"
        };
    } else {
        return paragraph;
    }
}

var options = {
    transformDocument: mammoth.transforms.paragraph(transformParagraph),
    styleMap: [
        "p[style-name='Code'] => pre:separator('\n')"
    ]
};

mammoth.transforms.paragraph(transformParagraph)

返回一个可用作 transformDocument 选项的函数。 这将对每个段落元素应用 transformParagraph 函数。 transformParagraph 应返回新的段落。

mammoth.transforms.run(transformRun)

返回一个可用作 transformDocument 选项的函数。 这将对每个运行元素应用 transformRun 函数。 transformRun 应返回新的运行。

mammoth.transforms.getDescendants(element)

获取元素的所有后代。

mammoth.transforms.getDescendantsOfType(element, type)

获取元素的特定类型的所有后代。 例如，要获取段落 paragraph 内的所有运行：

var runs = mammoth.transforms.getDescendantsOfType(paragraph, "run");

编写样式映射

样式映射由多个样式映射组成，每个映射用换行符分隔。 空行和以 # 开头的行将被忽略。

一个样式映射有两个部分：

• 箭头左侧是文档元素匹配器。
• 箭头右侧是 HTML 路径。

在转换每个段落时， Mammoth 会找到第一个文档元素匹配器与当前段落匹配的样式映射。 然后 Mammoth 确保满足 HTML 路径。

新鲜度

在编写样式映射时，理解 Mammoth 的新鲜度概念很有帮助。 在生成时，Mammoth 只会在必要时关闭 HTML 元素。 否则，元素会被重用。

例如，假设指定的样式映射之一是 p[style-name='Heading 1'] => h1。 如果 Mammoth 遇到一个样式名为 Heading 1 的 .docx 段落， 该 .docx 段落将被转换为具有相同文本的 h1 元素。 如果下一个 .docx 段落也具有样式名 Heading 1， 那么该段落的文本将被追加到现有的 h1 元素中， 而不是创建一个新的 h1 元素。

在大多数情况下，你可能希望生成一个新的 h1 元素。 你可以使用 :fresh 修饰符来指定这一点：

p[style-name='Heading 1'] => h1:fresh

这样，两个连续的 Heading 1 .docx 段落将被转换为两个独立的 h1 元素。

重用元素在生成更复杂的 HTML 结构时很有用。 例如，假设你的 .docx 包含旁注。 每个旁注可能有一个标题和一些正文文本， 这些应该包含在一个单独的 div.aside 元素中。 在这种情况下，类似 p[style-name='Aside Heading'] => div.aside > h2:fresh 和 p[style-name='Aside Text'] => div.aside > p:fresh 的样式映射可能会很有帮助。

文档元素匹配器

段落、运行和表格

匹配任何段落：

p

匹配任何运行：

r

匹配任何表格：

table

要匹配具有特定样式的段落、运行或表格， 你可以通过名称引用样式。 这是在 Microsoft Word 或 LibreOffice 中显示的样式名称。 例如，要匹配样式名为 Heading 1 的段落：

p[style-name='Heading 1']

你也可以通过前缀匹配样式名。 例如，要匹配样式名以 Heading 开头的段落：

p[style-name^='Heading']

样式也可以通过样式 ID 引用。 这是 .docx 文件内部使用的 ID。 要匹配具有特定样式 ID 的段落或运行， 在样式 ID 前加上一个点。 例如，要匹配样式 ID 为 Heading1 的段落：

p.Heading1

粗体

匹配显式设置为粗体的文本：

b

请注意，这只匹配已明确应用粗体的文本。 它不会匹配因段落或运行样式而变为粗体的任何文本。

斜体

匹配明确的斜体文本：

i

请注意，这只匹配已明确应用斜体的文本。 它不会匹配因段落或运行样式而变为斜体的任何文本。

下划线

匹配明确带下划线的文本：

u

请注意，这只匹配已明确应用下划线的文本。 它不会匹配因段落或运行样式而带有下划线的任何文本。

删除线

匹配明确带删除线的文本：

strike

请注意，这只匹配已明确应用删除线的文本。 它不会匹配因段落或运行样式而带有删除线的任何文本。

全大写

匹配明确全大写的文本：

all-caps

请注意，这只匹配已明确应用全大写的文本。 它不会匹配因段落或运行样式而全大写的任何文本。

小型大写字母

匹配明确使用小型大写字母的文本：

small-caps

请注意，这只匹配已明确应用小型大写字母的文本。 它不会匹配因段落或运行样式而使用小型大写字母的任何文本。

高亮

匹配明确高亮的文本：

highlight

请注意，这只匹配已明确应用高亮的文本。 它不会匹配因段落或运行样式而高亮的任何文本。

还可以匹配特定颜色。 例如，要匹配黄色高亮：

highlight[color='yellow']

通常使用的颜色集包括：

• black（黑色）
• blue（蓝色）
• cyan（青色）
• green（绿色）
• magenta（洋红色）
• red（红色）
• yellow（黄色）
• white（白色）
• darkBlue（深蓝色）
• darkCyan（深青色）
• darkGreen（深绿色）
• darkMagenta（深洋红色）
• darkRed（深红色）
• darkYellow（深黄色）
• darkGray（深灰色）
• lightGray（浅灰色）

忽略文档元素

使用!来忽略文档元素。 例如，要忽略任何样式为Comment的段落：

p[style-name='Comment'] => !

HTML路径

单个元素

最简单的HTML路径是指定单个元素。 例如，指定一个h1元素：

h1

要给元素添加CSS类， 在元素后面添加一个点，然后是类名：

h1.section-title

要添加属性，使用方括号，类似于CSS属性选择器：

p[lang='fr']

要要求元素是新的，使用:fresh：

h1:fresh

修饰符必须按正确顺序使用：

h1.section-title:fresh

分隔符

要指定在合并在一起的段落内容之间放置的分隔符， 使用:separator('分隔符字符串')。

例如，假设文档包含一个代码块，其中每行代码都是一个样式为Code Block的段落。 我们可以编写一个样式映射，将这些段落映射到<pre>元素：

p[style-name='Code Block'] => pre

由于pre没有标记为:fresh， 连续的pre元素将被合并在一起。 然而，这会导致代码都在一行上。 我们可以使用:separator在每行代码之间插入换行符：

p[style-name='Code Block'] => pre:separator('\n')

嵌套元素

使用>来指定嵌套元素。 例如，要指定div.aside内的h2：

div.aside > h2

你可以将元素嵌套到任何深度。

升级到更高版本

1.0.0

不再支持convertUnderline选项。 使用样式映射来控制如何处理下划线。

0.3.0

如果你定义了自定义样式映射或使用了文档转换， 你可能需要稍微改变你的用法。 否则，你应该能够继续像以前一样使用Mammoth。

自定义样式映射

在0.3.0之前，Mammoth使用样式ID匹配docx段落，例如p.Heading1。 这些ID在docx格式内部使用， 与样式名称不同 即Microsoft Word或LibreOffice显示的名称。 虽然Mammoth仍然支持通过ID匹配样式， 但更推荐通过名称匹配样式。 例如，不要使用：

p.AsideHeading => h1

更推荐使用：

p[style-name='Aside Heading'] => h1

文档转换

在0.3.0之前， Mammoth（误导性地）将样式ID分配给一个名为styleName的属性。 现在样式ID被分配给一个更合适的属性styleId。 styleName属性现在被设置为样式的名称。 要保留现有行为， 应该以以下两种方式之一重写任何现有的文档转换：

• 设置styleId属性而不是styleName属性

• 将styleName属性设置为样式的名称，而不是ID

0.2.0

函数mammoth.style()被重命名为mammoth.styleMapping()。

致谢

感谢以下人员对Mammoth的贡献：

• Craig Leinoff：

  • 文档转换

• John McLear：

  • 下划线支持

• Chris Price：

  • node.js Buffer支持
  • UTF8 BOM处理

• Stoo Goff

  • Markdown支持

• Andreas Lubbe

  • 内部超链接支持

• Jacob Wang

  • 支持无名称定义的样式

捐赠

如果你想表示感谢，欢迎通过Ko-fi进行捐赠。

如果你在业务中使用Mammoth， 请考虑通过每周在Liberapay上捐赠来支持Mammoth的持续维护。