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支持
• 文檔變換