Mammoth官方文档翻译

用于.NET平台.docx转HTML的Mammoth

Mammoth可用于将.docx文档（比如由Microsoft Word创建的）转换为HTML。Mammoth致力于通过文档中的语义信息生成简洁的HTML，而忽略一些其他细节。例如，Mammoth会把带有“Heading 1”样式的所有段落转换为“h1”元素，而不是试图精确地复制标题的所有样式（字体、字号、颜色等）。

.docx使用的结构与HMTL的结构有很多不匹配的地方，这意味着复杂文档的转换很难达到完美。但如果你仅使用样式进行文档的语义化标记，Mammoth将会工作得很好。

当前支持如下特性：

• 标题。
• 列表。
• 自定义从.docx样式到HTML的映射。比如，通过提供合适的样式映射，可以把“WarningHeading”样式转换为“h1.warning”类。
• 表格。表格自身的样式——比如边框——目前会被忽略，但对文本格式的处理与文档的其余部分一致。
• 脚注和尾注。
• 图像。
• 粗体、斜体、下划线、删除线、上标和下标。
• 链接。
• 换行。
• 文本框。文本框中的内容作为一个单独的段落处理，放在包含该文本框的段落之后。

安装

可从Nuget上获取。

Install-Package Mammoth

支持的其他平台

• JavaScript，包括浏览器和node.js。可从npm上获取。
• Python。可从PyPI上获取。
• WordPress。
• Java/JVM。可从Maven Central上获取。

使用

库

基本转换

要将一个已经存在的.docx文件转换为HTML，只需创建DocumentConverter的一个实例，并将文件路径传递给ConvertToHtml方法。例如：

using Mammoth;

var converter = new DocumentConverter();
var result = converter.ConvertToHtml("document.docx");
var html = result.Value; // 生成的HTML
var warnings = result.Warnings; // 转换期间产生的所有警告

你也可以使用ExtractRawText方法提取文档的纯文本。这会忽略文档中的所有格式。每个段落后跟两个换行符。

var converter = new DocumentConverter();
var result = converter.ExtractRawText("document.docx");
var html = result.Value; // 纯文本
var warnings = result.Warnings; // 转换期间产生的所有警告

自定义样式映射

默认情况下，Mammoth把一些普通的.docx样式映射为HTML元素。比如，带有名为“Heading 1”的样式的一个段落会被转换为一个“h1”元素。关于样式映射语法的描述包含在“编写样式映射配置”一节中。例如，将带有名为“Section Title”的样式的段落转换为“h1”元素，带有名为“Subsection Title”的样式的段落转换为“h2”元素：

var converter = new DocumentConverter()
    .AddStyleMap("p[style-name='Section Title'] => h1:fresh")
    .AddStyleMap("p[style-name='Subsection Title'] => h2:fresh");

也可以将整个样式映射作为一个字符串传递，当样式映射存储在文本文件中时，这会很有用：

var styleMap =
    "p[style-name='Section Title'] => h1:fresh\n" +
    "p[style-name='Subsection Title'] => h2:fresh";
var converter = new DocumentConverter()
    .AddStyleMap(styleMap);

后添加的样式映射拥有较高的优先级。用户定义的样式映射优于默认样式映射。如果要禁用所有的默认样式映射，可调用DisableDefaultStyleMap方法：

var converter = new DocumentConverter()
    .DisableDefaultStyleMap();

粗体

默认情况下，粗体文本被包装在“<strong>”标签中。可以通过添加对“b”的样式映射改变这种行为。比如，要把粗体文本包装在“<em>”标签中：

var converter = new DocumentConverter()
    .AddStyleMap("b => em");

斜体

默认情况下，斜体文本被包装在“<em>”标签中。可以通过添加对“i”的样式映射改变这种行为。比如，要把斜体文本包装在“<strong>”标签中：

var converter = new DocumentConverter()
    .AddStyleMap("i => strong");

下划线

默认情况下，由于会与HTML文档中的链接引起混淆，所有文本的下划线均被忽略。可以通过添加对“u”的样式映射改变这种行为。比如，有一个源文档使用下划线表示强调。下面的代码会把所有带显式下划线的源文本包装在“<em>”标签中：

var converter = new DocumentConverter()
    .AddStyleMap("u => em");

删除线

默认情况下，带删除线的文本被包装在“<s>”标签中。可以通过添加对“strike”的样式映射改变这种行为。比如，要把带删除线的文本包装在“<del>”标签中：

var converter = new DocumentConverter()
    .AddStyleMap("strike => del");

API

DocumentConverter

方法：

• IResult<string> ConvertToHtml(string path)：将由path参数指定的文件转换为一个HTML字符串。
• IResult<string> ConvertToHtml(Stream stream)：将由stream参数指定的流转换为一个HTML字符串。注意，使用这个方法，而不是convertToHtml(File file)方法意味着指向其他文件——比如图片——的相对路径将无法解析。
• IResult<string> ExtractRawText(string path)：提取文档中的纯文本。这将忽略文档中的所有格式。每个段落后跟两个换行符。
• IResult<string> ExtractRawText(Stream stream)：提取文档中的纯文本。 这将忽略文档中的所有格式。每个段落后跟两个换行符。
• DocumentConverter AddStyleMap(string styleMap)：添加用于指定Word样式到HTML的映射的样式映射。最后添加的样式映射具有最高的优先级。“编写样式映射配置”一节提供了对其语法的说明。
• DocumentConverter DisableDefaultStyleMap()：默认情况下，任何新添加的样式映射都会跟默认样式映射合并起来。调用这个方法可以停用默认样式映射。
• DocumentConverter PreserveEmptyParagraphs()：默认情况下，空段落将会被忽略。调用这个方法可以在输出中保留空段落。
• DocumentConverter IdPrefix(string idPrefix)：设置生成的任何ID的前缀，比如用于书签、脚注和尾注等的ID。默认为空字符串。

IResult<T>

表示转换的结果。属性：

• T Value：生成的文本。
• ISet<string> Warnings：转换期间生成的所有警告。

编写样式映射配置

一个样式映射配置由几个使用换行符分隔的样式映射组成。空行和由“#”开始的行会被忽略。

一个样式映射由两部分组成：

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

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

新建元素

当编写样式映射时，理解Mammoth中关于新建元素的概念是很有用的。在生成HTML的时候，Mammoth仅在必要的时候才会关闭一个HTML元素。否则，元素会被重用。

例如，有一个样式映射为“p[style-name='Heading 1'] => h1”。如果Mammoth遇到了一个包含名为“Heading 1”的样式的段落，这个段落会被转换为包含相同文本的“h1”元素。如果下一个段落也包含名为“Heading 1”的样式，那么这个段落的文本会被追加到已有的“h1”元素，而不是创建一个新的“h1”元素。

许多情况下，你可能希望生成一个新的“h1”元素。你可以通过使用“:fresh”修饰符指明这么做：

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

然后两个连续的“Heading 1”段落会被转换为两个独立的“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

要匹配带有指定样式的段落和内联文本，你可以通过名称引用样式，即显示在Microsoft Word或LibreOffice中的样式名称。比如，要匹配一个带有样式名“Heading 1”的段落：

p[style-name='Heading 1']

也可以通过样式ID引用样式，即在.docx文件内部使用的ID。要匹配一个带有指定样式ID的段落或内联文本，追加一个点，后跟样式ID即可。比如，要匹配一个带有样式ID“Heading1”的段落：

p.Heading1

粗体

匹配显式的粗体文本：

b

注意，这只会匹配显式地应用了粗体样式的文本，而不会匹配由于其所属段落或内联文本的样式而显示为粗体的文本。

斜体

匹配显式的斜体文本：

i

注意，这只会匹配显式地应用了斜体样式的文本，而不会匹配由于其所属段落或内联文本的样式而显示为斜体的文本。

下划线

匹配显式的下划线文本：

u

注意，这只会匹配显式地应用了下划线样式的文本，而不会匹配由于其所属段落或内联文本的样式而带有下划线的文本。

删除线

匹配显式的删除线文本：

strike

注意，这只会匹配显式地应用了删除线样式的文本，而不会匹配由于其所属段落或内联文本的样式而带有删除线的文本。

HTML路径

单一元素

最简单的HTML路径只指定单一元素。比如，要指定一个“h1”元素：

h1

要给元素指定一个CSS类，追加一个点，后跟类名即可：

h1.section-title

如果要求新建元素，使用“:fresh”：

h1:fresh

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

h1.section-title:fresh

嵌套元素

使用“>”指定嵌套元素。比如，要指定“h2”在“div.aside”中：

div.aside > h2

你可以嵌套任意深度的元素。

缺失的特性

与Mammoth的JavaScript和Python实现相比，如下特性暂缺：

• 自定义图片处理程序
• CLI
• 对嵌入样式映射配置的支持
• Markdown支持
• 文档变换