Mammoth .docx 到 HTML converter
Mammoth 旨在转换.docx文档,
such as those created by Microsoft Word, Google Docs 和 LibreOffice,
并将它们转换为 HTML。
Mammoth 旨在通过使用文档中的语义信息来生成简单干净的 HTML,
并忽略其他细节。
例如
Mammoth 将任何段落转换为 Heading 1 to h1 元素
而不是尝试精确复制标题的样式(字体、文本大小、颜色等)。
.docx 使用的结构与 HTML 的结构之间存在很大的不匹配,
这意味着转换不太可能完美地适用于更复杂的文档。
如果您仅使用样式在语义上标记文档,则 Mammoth 效果最佳。
的 following features are currently 支持ed:
-
标题。
-
列表。
-
从您自己的 docx 样式到 HTML 的可自定义映射。
For instance, you could convertWarningHeadingtoh1.warning通过提供适当的样式映射。 -
表。
The formatting of the table itself, such as borders, is currently ignored,
but the formatting of the text is treated the same as in the rest of the document. -
脚注和尾注。
-
图片.
-
大胆, italics, underlines, strikethrough, superscript and subscript.
-
链接。
-
换行符。
-
文本框。文本框的内容被视为单独的段落
that appears after the paragraph containing the text box. -
评论。
网络演示
这 easiest way to try out mammoth is to use the web demo:
- 克隆此存储库
- 跑
make setup - 打开
browser-demo/index.html在网络浏览器中
安装
npm install mammoth
其他支持的平台
-
Java/JVM.
Available [on Maven Central](http://search.maven.org/#search|ga|1|g:“org.zwobble.mammoth” AND a:“mammoth”).
使用说明
命令行界面
您可以通过传递 docx 文件和输出文件的路径来转换 docx 文件。
例如:
mammoth document.docx output.html
如果 no output file is specified, output is written to stdout instead.
输出是一个 HTML 片段,而不是一个完整的 HTML 文档,用 UTF-8 编码。
由于编码未在片段中显式设置,
如果浏览器未默认为 UTF-8,则在 Web 浏览器中打开输出文件可能会导致 Unicode 字符呈现不正确。
Mammoth 不对源文档进行清理,
因此,对于不受信任的用户输入,应非常小心地使用。
看 the 安全 部分了解更多信息。
Images
默认情况下,图像内联包含在输出 HTML 中。
如果输出目录由 --output-dir,
图像将写入单独的文件。
例如:
mammoth document.docx --output-dir=output-dir
现有文件(如果存在)将被覆盖。
风格
可以使用以下命令从文件中读取自定义样式图 --style-map.
For instance:
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 支持已弃用。
建议生成 HTML 并使用单独的库将 HTML 转换为 Markdown,
并且可能会产生更好的结果。
使用 --output-format=markdown 将导致生成 Markdown。
For instance:
mammoth document.docx --output-format=markdown
图书馆
在node.js和浏览器中,可以按照通常的方式需要猛犸象:
1 var mammoth = require("mammoth");
或者,您可以使用**的 JavaScript 文件 mammoth.browser.js,
其中包括猛犸象及其依赖项。
这使用任何加载的模块系统。
例如,当使用 CommonJS 时:
1 var mammoth = require("mammoth/mammoth.browser");
如果未找到模块系统,
mammoth 设置为窗口全局。
可以使用以下命令生成该文件 make setup 在开发过程中。
Mammoth performs no sanitisation of the source document,
and should therefore be used extremely carefully with untrusted user input.
请参阅 Security section for more information.
基本转换
要将现有.docx文件转换为 HTML,请使用 mammoth.convertToHtml:
12345678910 var mammoth = require("mammoth"); mammoth.convertToHtml({path: "path/to/document.docx"}) .then(function(result){ var html = result.value; // The generated HTML var messages = result.messages; // Any messages, such as warnings during conversion }) .catch(function(error) { console.error(error); });
请注意 mammoth.convertToHtml 返回一个promise.
您还可以使用 mammoth.extractRawText.
这将忽略文档中的所有格式。
每个段落后面有两个换行符。
12345678 mammoth.extractRawText({path: "path/to/document.docx"}) .then(function(result){ var text = result.value; // The raw text var messages = result.messages; }) .catch(function(error) { console.error(error); });
自定义样式地图
默认情况下,
Mammoth 将一些常见的.docx样式映射到 HTML 元素。
For instance,
样式名称为 Heading 1 转换为h1 元素。
您可以通过将 options 对象与 styleMap 财产 as a second argument to convertToHtml.
样式贴图语法的描述可以在以下部分找到 “Writing style maps”.
例如,如果样式名称为 Section Title 应转换为h1 elements,
以及样式名称为“的段落 Subsection Title should be converted to h2 元素:
123456789 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 也可以是字符串。
每行都被视为单独的样式映射,
忽略空行和以 #:
12345 var options = { styleMap: "p[style-name='Section Title'] => h1:fresh" + "p[style-name='Subsection Title'] => h2:fresh"};
用户定义的样式映射优先于默认样式映射。
要完全停止使用默认样式映射,
设置 options.includeDefaultStyleMap to false:
1234567 var options = { styleMap: [ "p[style-name='Section Title'] => h1:fresh", "p[style-name='Subsection Title'] => h2:fresh" ], includeDefaultStyleMap: false};
自定义图像处理程序
默认情况下,图像被转换为 元素,其源内联包含在src 属性。
可以通过设置 convertImage 选项设置为image converter .
例如,以下内容将复制默认行为:
123456789 var options = { convertImage: mammoth.images.imgElement(function(image) { return image.read("base64").then(function(imageBuffer) { return { src: "data:" + image.contentType + ";base64," + imageBuffer }; }); })};
Bold
默认情况下,粗体文本换行 标签。
可以通过添加 b.
例如,将粗体文本换行 标签:
12345678 var mammoth = require("mammoth"); var options = { styleMap: [ "b => em" ]};mammoth.convertToHtml({path: "path/to/document.docx"}, options);
斜体
默认情况下,斜体文本换行在 tags.
This behaviour can be changed by adding a style mapping for i.
例如,将斜体文本换行 tags:
12345678 var mammoth = require("mammoth"); var options = { styleMap: [ "i => strong" ]};mammoth.convertToHtml({path: "path/to/document.docx"}, options);
下划线
默认情况下,任何文本的下划线都会被忽略,因为下划线可能与 HTML 文档中的链接混淆。
This behaviour can be changed by adding a style mapping for u.
例如,假设源文档使用下划线来强调。
以下内容将把任何显式带下划线的源文本换行 tags:
12345678 var mammoth = require("mammoth"); var options = { styleMap: [ "u => em" ]};mammoth.convertToHtml({path: "path/to/document.docx"}, options);
删除线
默认情况下,删除线文本换行在 tags.
This behaviour can be changed by adding a style mapping for strike.
例如,将删除线文本换行 tags:
12345678 var mammoth = require("mammoth"); var options = { styleMap: [ "strike => del" ]};mammoth.convertToHtml({path: "path/to/document.docx"}, options);
评论
默认情况下,注释将被忽略。
要在生成的 HTML 中包含注释,
添加 的样式映射 comment-reference.
For instance:
12345678 var mammoth = require("mammoth"); var options = { styleMap: [ "comment-reference => sup" ]};mammoth.convertToHtml({path: "path/to/document.docx"}, options);
注释将附加到文档末尾,
使用指定的样式映射包装到注释的链接。
应用程序接口
mammoth.convertToHtml(input, options)
将源文档转换为 HTML。
-
input:描述源文档的对象。
On node.js, the following inputs are supported:{path: path}哪里path是.docx文件的路径。{buffer: buffer}, wherebuffer是包含.docx文件的node.js缓冲区。
在浏览器中,支持以下输入:
{arrayBuffer: arrayBuffer}, wherearrayBuffer是包含.docx文件的数组缓冲区。
-
options(可选):转换选项。
May have the following properties:-
styleMap:控制 Word 样式到 HTML 的映射。
Ifoptions.styleMap是一个字符串,
each line is treated as a separate style mapping,
ignoring blank lines and lines starting with#:
Ifoptions.styleMap是一个数组,
each element is expected to be a string representing a single style mapping.
See “Writing style maps” 以获取对样式贴图语法的引用。 -
includeEmbeddedStyleMap:默认情况下,
if the document contains an embedded style map, then it 与默认样式贴图相结合。
To ignore any embedded style maps,
setoptions.includeEmbeddedStyleMaptofalse. -
includeDefaultStyleMap: by default,
the style map passed instyleMapis combined with the default style map.
To stop using the default style map altogether,
setoptions.includeDefaultStyleMaptofalse. -
externalFileAccess:源文档可以引用源文档之外的文件。
Access to any such external files is disabled by default.
To enable access when converting trusted source documents,
setoptions.externalFileAccesstotrue. -
convertImage:默认情况下,图像将转换为elements with the source included inline in thesrcattribute.
Set this option to an image converter 以覆盖默认行为。 -
ignoreEmptyParagraphs:默认情况下,忽略空段落。
Set this option tofalse以保留输出中的空段落。 -
idPrefix:
a string to prepend to any generated IDs,
such as those used by bookmarks, footnotes and endnotes.
Defaults to an empty string. -
transformDocument:如果设置,
this function is applied to the document read from the docx file before the conversion to HTML.
The API for document transforms should be considered unstable.
See document transforms.
-
-
返回包含结果的 Promise。
This result has the following properties:-
value:生成的 HTML -
messages:转换过程中生成的任何消息,例如错误和警告
-
mammoth.convertToMarkdown(input, options)
Markdown 支持 is deprecated.
Generating HTML and using a separate library to convert the HTML to Markdown is recommended,
and is likely to produce better results.
将源文档转换为 Markdown。
其行为与 convertToHtml,
除了 value 结果的属性包含 Markdown 而不是 HTML。
mammoth.extractRawText(input)
提取文档的原始文本。
This will ignore all formatting in the document.
Each paragraph is followed by two newlines.
-
input: an object describing the source document.
On node.js, the following inputs are supported:{path: path}, wherepathis the path to the .docx file.{buffer: buffer}, wherebufferis a node.js Buffer containing a .docx file.
In the browser, the following inputs are supported:
{arrayBuffer: arrayBuffer}, wherearrayBufferis an array buffer containing a .docx file.
-
Returns a promise containing a result.
This result has the following properties:-
value:原始文本 -
messages:任何消息,例如错误和警告
-
mammoth.embedStyleMap(input, styleMap)
给定一个现有的 docx 文件,
embedStyleMap 将生成一个新的 docx 文件,其中嵌入了传递的样式映射。
当 Mammoth 读取新的 docx 文件时,
它将使用嵌入式样式图。
-
input: an object describing the source document.
On node.js, the following inputs are supported:{path: path}, wherepathis the path to the .docx file.{buffer: buffer}, wherebufferis a node.js Buffer containing a .docx file.
In the browser, the following inputs are supported:
{arrayBuffer: arrayBuffer}, wherearrayBufferis an array buffer containing a .docx file.
-
styleMap:要嵌入的样式贴图。 -
返回一个 Promise。
CalltoArrayBuffer()在 promise 内的值上得到一个ArrayBuffer表示新文档。
CalltoBuffer()在 promise 内的值上获取一个Bufferrepresenting the new document.
For instance:
1234 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).
这会创建一个 元素。
func 应该是一个具有一个参数的函数image.
此参数是正在转换的图像元素,
并具有以下属性:
-
contentType:图片的内容类型,例如image/png. -
readAsArrayBuffer():将图像文件读取为ArrayBuffer.
Returns a promise of anArrayBuffer. -
readAsBuffer():将图像文件读取为Buffer.
Returns a promise of aBuffer.
This is not supported in browsers unless aBuffer已使用聚填充物。 -
readAsBase64String():将图像文件读取为 base64 编码的字符串。
Returns a promise of astring. -
read([encoding])(已弃用):读取具有指定编码的图像文件。
If an encoding is specified, a promise of astring被返回。
If no encoding is specified, a promise of aBufferis returned.
func 应该返回一个对象(或一个对象的 Promise)属性,用于 element.
这至少应包括 src attribute.
如果找到图像的任何替代文本,
这将自动添加到元素的属性中。
例如,以下内容复制了默认图像转换:
1234567 mammoth.images.imgElement(function(image) { return image.readAsBase64String().then(function(imageBuffer) { return { src: "data:" + image.contentType + ";base64," + imageBuffer }; });})
mammoth.images.dataUri 是默认的图像转换器。
Security
Mammoth performs no sanitisation of the source document,
and should therefore be used extremely carefully with untrusted user input.
For instance:
-
源文档可以包含
javascript:目标。
If, for instance, you allow users to upload source documents,
automatically convert the document into HTML,
and embed the HTML into your website without sanitisation,
this may create links that can execute arbitrary JavaScript when clicked. -
源文档可以引用源文档之外的文件。
If, for instance, you allow users to upload source documents to a server,
automatically convert the document into HTML on the server,
and embed the HTML into your website,
this may allow arbitrary files on the server to be read and exfiltrated.为避免此问题,默认情况下禁用对任何此类外部文件的访问。
To enable access when converting trusted source documents,
setoptions.externalFileAccesstotrue.
文档转换
文档转换的 API 应被视为不稳定,
并且可能会在任何版本之间更改。
如果关于这种行为,
您应该固定到特定版本的mammoth.js,
并在更新前仔细测试。*
Mammoth 允许在转换文档之前对其进行转换。
For instance,
假设该文档尚未在语义上标记,
但你知道任何居中对齐的段落都应该是一个标题。
您可以使用 transformDocument 参数来适当修改文档:
123456789101112131415161718192021222324 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:
1234567891011 function transformParagraph(element) { if (element.alignment === "center" && !element.styleId) { return {...element, styleId: "Heading2"}; } else { return element; }} var options = { transformDocument: mammoth.transforms.paragraph(transformParagraph)};
或者,如果您希望已显式设置为使用等宽字体表示代码的段落:
12345678910111213141516171819202122232425 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('')" ]};
mammoth.transforms.paragraph(transformParagraph)
返回一个可用作 transformDocument 选择。
这将应用函数 transformParagraph 添加到每个段落元素。
transformParagraph 应返回新段落。
mammoth.transforms.run(transformRun)
Returns a function that can be used as the transformDocument option.
This will apply the function transformRun 到每个运行元素。
transformRun 应返回新的运行。
mammoth.transforms.getDescendants(element)
获取元素的所有后代。
mammoth.transforms.getDescendantsOfType(element, type)
获取特定类型的元素的所有后代。
例如,要获取元素内的所有运行 paragraph:
1 var runs = mammoth.transforms.getDescendantsOfType(paragraph, "run");
Writing style maps
样式映射由多个由换行符分隔的样式映射组成。
空行和以 # 被忽略。
样式映射由两部分组成:
- 左侧箭头之前是文档元素匹配器。
- 右侧箭头后面是 HTML 路径。
转换每个段落时,
Mammoth 找到文档元素匹配器与当前段落匹配的第一个样式映射。
然后,Mammoth 确保满足 HTML 路径。
新鲜
在编写风格映射时,理解 Mammoth 的新鲜度概念会很有帮助。
生成时,Mammoth 只会在必要时关闭 HTML 元素。
否则,将重复使用元素。
例如,假设指定的样式映射之一是 p[style-name='Heading 1'] => h1.
如果 Mammoth 遇到.docx样式名称为 Heading 1,
.docx段落将转换为 h1 元素。
如果下一个.docx段落也具有样式名称 Heading 1,
则该段落的文本将附加到 现存 h1 元素
而不是创建一个新的 h1 element.
在大多数情况下,您可能希望生成一个新的 h1 元素。
您可以使用 :fresh 修饰语:
p[style-name='Heading 1'] => h1:fresh
两连 Heading 1 然后.docx段落将转换为两个单独的段落h1 元素。
重用元素对于生成更复杂的 HTML 结构很有用。
例如,假设您的.docx包含旁白。
每个旁白可能都有一个标题和一些正文,
which should be contained 在a single div.aside element.
在这种情况下,类似于 p[style-name='Aside Heading'] => div.aside > h2:fresh and
p[style-name='Aside Text'] => div.aside > p:fresh 可能会有所帮助。
文档元素匹配器
段落、运行和表格
匹配任何段落:
1 p
匹配任何运行:
1 r
匹配任何表:
1 table
要将段落、运行或表格与特定样式匹配,
您可以按名称引用样式。
这是在 Microsoft Word 或 LibreOffice 中显示的样式名称。
例如,将段落与样式名称匹配 Heading 1:
1 p[style-name='Heading 1']
您还可以按前缀匹配样式名称。
例如,要匹配样式名称以 Heading:
1 p[style-name^='Heading']
样式也可以通过样式 ID 引用。
这是.docx文件内部使用的 ID。
要匹配具有特定样式 ID 的段落或运行,
附加一个点,后跟样式 ID。
例如,将段落与样式 ID 匹配 Heading1:
1 p.Heading1
Bold
匹配显式粗体文本:
1 b
请注意,这与显式应用了粗体的文本匹配。
它不会匹配任何因其段落或运行样式而加粗的文本。
Italic
匹配显式斜体文本:
1 i
请注意,这与已显式应用斜体的文本匹配。
它不会匹配任何因其段落或运行样式而呈斜体的文本。
Underline
匹配显式下划线文本:
1 u
请注意,这与已显式应用下划线的文本匹配。
它不会匹配任何因其段落或运行样式而带有下划线的文本。
删除线
匹配显式删除线文本:
1 strike
请注意,这与已显式应用删除线的文本匹配。
它不会匹配任何因其段落或运行样式而被删除的文本。
全部大写
显式匹配全部大写文本:
1 all-caps
请注意,这与显式应用了全部大写的文本匹配。
由于其段落或运行样式,它不会匹配任何全部大写的文本。
小型大写字母
匹配显式小写字母文本:
1 small-caps
请注意,这与已明确应用小写字母的文本匹配。
由于其段落或运行样式,它不会匹配任何小写字母的文本。
高亮
匹配显式突出显示的文本:
1 highlight
请注意,这与已显式应用突出显示的文本匹配。
它不会匹配因段落或运行样式而突出显示的任何文本。
还可以匹配特定的颜色。
例如,要匹配黄色高亮:
1 highlight[color='yellow']
通常使用的颜色集是:
blackbluecyangreenmagentaredyellowwhitedarkBluedarkCyandarkGreendarkMagentadarkReddarkYellowdarkGraylightGray
忽略文档元素
使用 ! 以忽略文档元素。
例如,忽略任何具有 Comment:
1 p[style-name='Comment'] => !
HTML 路径
单元素
最简单的 HTML 路径是指定单个元素。
例如,要指定 an h1 元素:
1 h1
要给一个元素一个 CSS 类,
附加一个点,后跟类名:
1 h1.section-title
要添加属性,请使用与 CSS 属性选择器类似的方括号:
1 p[lang='fr']
要要求元素是新鲜的,请使用 :fresh:
1 h1:fresh
修饰符必须按正确的顺序使用:
1 h1.section-title:fresh
分隔符
要指定要在折叠在一起的段落内容之间放置分隔符,
用 :separator('SEPARATOR STRING').
例如,假设文档包含一个代码块,其中每一行代码都是一个样式为 Code Block.
我们可以编写一个样式映射来将此类段落映射到
elements:
1 p[style-name='Code Block'] => pre
因为 pre 未标记为:fresh,
连续的 pre 元素将一起折叠。
但是,这会导致代码全部位于一行上。
我们可以使用 :separator 要在每行代码之间**换行符:
12 p[style-name='Code Block'] => pre:separator('')
嵌套元素
Use > 以指定嵌套元素。
For instance, to specify h2 within div.aside:
1 div.aside > h2
您可以将元素嵌套到任意深度。
升级到更高版本
1.0.0
The convertUnderline 选项不再受支持。
使用样式映射来控制下划线的处理方式。
0.3.0
如果已定义自定义样式图或使用文档转换,
您可能需要稍微改变您的用法。
否则,您应该能够像以前一样继续使用 Mammoth。
自定义样式地图
在 0.3.0 之前,Mammoth 使用样式 ID 匹配 docx 段落,例如 p.Heading1.
这些 ID 在内部以 docx 格式使用
并且与样式名称不同
即 Microsoft Word 或 LibreOffice 显示的名称。
虽然猛犸象仍然支持通过ID匹配样式,
首选按名称匹配样式。
例如,而不是:
p.AsideHeading => h1
喜欢:
p[style-name='Aside Heading'] => h1
Document transforms
在 0.3.0 之前,
Mammoth(误导性地)将样式 ID 分配给名为 styleName.
样式 ID 现在分配给更合适的属性 styleId.
The styleName 属性现在设置为样式的名称。
为了保留现有行为,
任何现有文档转换都应通过以下两种方式之一重写:
-
将
styleId属性而不是styleNameproperty -
Set the
styleName属性设置为样式的名称,而不是 ID
0.2.0
功能 mammoth.style() 已重命名为mammoth.styleMapping().
确认
感谢以下人员对猛犸象的贡献:
-
- Document transforms
-
- 下划线支持
-
- node.js
Buffersupport - UTF8 BOM 处理
- node.js
-
- Markdown support
-
- 内部超链接支持
-
- 支持定义不带名称的样式
捐款
如果您想表示感谢,请随时 make a donation through Ko-fi.
如果您将 Mammoth 用作业务的一部分,
请考虑通过以下方式支持 Mammoth 的持续维护 making a weekly donation through Liberapay.
免责声明 © 2025 - 虚宝阁
本站部分源码来源于网络,版权归属原开发者,用户仅获得使用权。依据《计算机软件保护条例》第十六条,禁止:
- 逆向工程破解技术保护措施
- 未经许可的分发行为
- 去除源码中的原始版权标识
※ 本站源码仅用于学习和研究,禁止用于商业用途。如有侵权, 请及时联系我们进行处理。