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支持
  • 文档变换
posted @ 2017-01-14 20:31  zhu'sDevlog  阅读(7644)  评论(0编辑  收藏  举报