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