在 GroupDocs.Viewer for .NET 中渲染電子郵件訊息並取得電子郵件屬性 ^[draft]

1. 介紹

GroupDocs.Viewer for .NET 函式庫讓您可以匯入任何常見格式的電子郵件訊息，將其渲染為 HTML、PNG、JPEG 和 PDF，並且在不實際渲染的情況下提取基本的電子郵件訊息屬性。

實際上，在使用 GroupDocs.Viewer 處理電子郵件訊息時，使用者應該了解兩種與電子郵件相關的類型：

• Options.EmailOptions 類別 – 讓您控制訊息的渲染方式（頁面大小、日期格式、欄位等）。
• Results.MailMessageViewInfo — 由 GroupDocs.Viewer 在呼叫 GetViewInfo() 方法後產生，保存已載入電子郵件訊息的中繼資料。

以下是一個非常快速的指南，說明如何渲染電子郵件訊息並取得其中繼資料。

2. 載入電子郵件訊息並渲染為所有輸出格式

下面的簡短程式碼示例展示了如何將輸入的電子郵件訊息「sample.eml」載入到 Viewer 類的實例中，然後渲染為四種支援的輸出格式：HTML、PDF、PNG 和 JPEG。正如您所見，開始時會實例化四個視圖選項類別，接著透過檔案路徑將「sample.eml」載入 Viewer 實例，最後呼叫四次 Viewer.View()。

using GroupDocs.Viewer;
using GroupDocs.Viewer.Options;


HtmlViewOptions htmlOptions = HtmlViewOptions.ForEmbeddedResources("html-page{0}.html");
PdfViewOptions pdfOptions = new PdfViewOptions("Output.pdf");
PngViewOptions pngOptions = new PngViewOptions("image-page{0}.png");
JpgViewOptions jpegOptions = new JpgViewOptions("image-page{0}.jpeg");

using (Viewer viewer = new Viewer("sample.eml"))
{
    viewer.View(htmlOptions);
    viewer.View(pdfOptions);
    viewer.View(pngOptions);
    viewer.View(jpegOptions);
}

3. 調整電子郵件渲染選項

上面的範例展示了所有選項均使用預設值進行渲染。然而，EmailOptions 類別存在於所有四個視圖選項（HtmlViewOptions、PdfViewOptions、PngViewOptions、JpgViewOptions）的 EmailOptions 屬性中。無需手動建立 EmailOptions 實例並指派給視圖選項——這些已自動完成，使用者只需在需要時調整屬性值即可。

EmailOptions 類別包含多個屬性，說明如下。

3.1. 頁面大小

控制輸出頁面的尺寸。預設為 Unspecified —— GroupDocs.Viewer 會自動調整為最合適的大小。可以這樣設定，例如：

PdfViewOptions pdfOptions = new PdfViewOptions("Output.pdf");
pdfOptions.EmailOptions.PageSize = PageSize.A1;

3.2. 日期與時間格式以及時區

電子郵件訊息通常包含「發送」日期。DateTimeFormat 屬性允許您控制此日期時間值的格式，TimeZoneOffset 則允許對此日期時間套用正向或負向的時差。以下範例：

JpgViewOptions jpegOptions = new JpgViewOptions("image-page{0}.jpeg");
jpegOptions.EmailOptions.DateTimeFormat = "MM d yyyy HH:mm tt zzz"; // 完全自訂格式
jpegOptions.EmailOptions.TimeZoneOffset = TimeSpan.FromHours(-5); // 向前調整 5 小時

如果將 DateTimeFormat 設為 null 或空字串，GroupDocs.Viewer 會使用系統當前的格式。

3.3. 調整欄位文字

郵件訊息包含正文以及主旨、發送時間、寄件者等欄位。GroupDocs.Viewer 允許使用者透過 FieldTextMap 屬性覆寫這些欄位的標籤，該屬性將 Field 列舉值（例如 Field.Subject）映射到渲染輸出中顯示的文字。因此使用者可以替換任何條目或新增條目：

PngViewOptions pngOptions = new PngViewOptions("image-page{0}.png");
pngOptions.EmailOptions.FieldTextMap[Field.Subject] = "Email Subject";
pngOptions.EmailOptions.FieldTextMap[Field.Sent] = "Mail was sent at";
pngOptions.EmailOptions.FieldTextMap[Field.From] = "Sender";

4. 載入電子郵件並取得其檢視資訊

您可以在不渲染電子郵件本身的情況下，程式化取得部分欄位值。為此，使用者應將電子郵件文件載入 Viewer 實例，然後呼叫 Viewer.GetViewInfo() 實例方法，如下所示：

using System;
using GroupDocs.Viewer;
using GroupDocs.Viewer.Options;
using GroupDocs.Viewer.Results;
// ...

using (Viewer viewer = new Viewer("sample.eml"))
{
    ViewInfo generalInfo = viewer.GetViewInfo(ViewInfoOptions.ForHtmlView());
    // 明確轉型
    MailMessageViewInfo mailMessageInfo = (MailMessageViewInfo)generalInfo;
    Console.WriteLine("From: {0}; Subject: {1}; Sent: {2}.", mailMessageInfo.From, mailMessageInfo.Subject, mailMessageInfo.Sent);

    // 如有需要，可渲染為任意輸出格式
    viewer.View(HtmlViewOptions.ForEmbeddedResources());
}

可以看到，Viewer.GetViewInfo() 方法返回的是通用的 ViewInfo 類別實例，然後再轉型為 MailMessageViewInfo 類別。目前僅支援 From、Subject 與 Sent 三個欄位。

以上三個屬性皆為唯讀。

5. 小結

• 建立 Viewer 實例，並在建構子中以路徑或串流指定輸入的電子郵件檔案。
• 呼叫 Viewer.GetViewInfo 方法，然後將其結果轉型為 MailMessageViewInfo 以取得 Sent、Subject、From 等中繼資料。
• 使用 EmailOptions 調整頁面大小、日期格式、時區偏移或任何欄位的文字標籤，最後呼叫 Viewer.View() 方法。

以上步驟即可取得核心的電子郵件屬性，並控制渲染時訊息的顯示方式，無需額外函式庫或複雜程式碼。

相關參考

• Render email messages as HTML, PDF, PNG, and JPEG files

取得免費試用

您可以從 releases.groupdocs.com 下載 GroupDocs.Viewer for .NET 的免費試用版。亦可從 here 取得臨時授權，以無限制地試用所有功能與特性。