在 GroupDocs.Viewer for .NET 中使用試算表

概述

Spreadsheet documents 是以表格形式——行與列——儲存資料的文件。它們也被稱為 workbooks。試算表文件有許多格式——Office Open XML（如 XLSX、XLSM 等）、Microsoft Excel Binary File Format（XLS、XLT）、OpenDocument Spreadsheet 格式（ODS、FODS、OTS）、基於文字的分隔符格式（CSV、TSV 等）等等。所有這些構成了所謂的 Spreadsheet formats family。GroupDocs.Viewer 幾乎支援所有試算表格式的匯入，並允許將它們轉換（渲染）為 HTML、PDF、PNG 和 JPEG。本文說明如何執行此操作、有哪些可用選項，以及何時、為何應使用它們。

基本用法

首先必須談談選項。公共 API 中有一個獨立的類別：SpreadsheetOptions 位於 GroupDocs.Viewer.Options 中。此類別專門用於調整 Spreadsheet formats family 的渲染方式。它可透過四種檢視選項的 SpreadsheetOptions 屬性取得：

• HtmlViewOptions.SpreadsheetOptions 用於將 Spreadsheet 文件渲染為 HTML，
• PdfViewOptions.SpreadsheetOptions 用於將 Spreadsheet 文件渲染為 PDF，
• PngViewOptions.SpreadsheetOptions 用於將 Spreadsheet 文件渲染為 PNG，
• JpgViewOptions.SpreadsheetOptions 用於將 Spreadsheet 文件渲染為 JPEG。

如果未明確指定，SpreadsheetOptions 屬性會隱含使用 SpreadsheetOptions 類別的預設實例，稍後本文會說明。

一眼看去，使用 GroupDocs.Viewer 渲染 Spreadsheet 文件非常簡單，與其他格式相同——建立一個 ViewOptions 實例，建立一個帶有指定輸入 Spreadsheet 文件的 Viewer 實例，然後呼叫 Viewer.View(viewOptions) 方法。以下程式碼示範將單一輸入 Spreadsheet 檔案渲染為四種輸出格式：HTML、PDF、PNG 與 JPEG。請注意，除了建立選項類別的實例外，沒有任何與試算表相關的調整，所有試算表選項皆使用預設值。

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

HtmlViewOptions htmlOptions = HtmlViewOptions.ForEmbeddedResources("worksheet_{0}.html");
PdfViewOptions pdfOptions = new PdfViewOptions("Output_spreadsheet.pdf");
PngViewOptions pngOptions = new PngViewOptions("worksheet_{0}.png");
JpgViewOptions jpegOptions = new JpgViewOptions("worksheet_{0}.jpeg");

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

現在來談談 工作表。每個試算表至少有一個工作表。在大多數表格處理軟體（如 Microsoft Excel）中，工作表以 分頁（tabs）的形式呈現。有些試算表格式可能只有單一工作表；例如所有基於文字的分隔符格式（CSV、TSV 等）。

預設情況下，GroupDocs.Viewer 會渲染給定試算表中的所有工作表。但這可以更改。Viewer.View() 方法有一個重載，接受第二個參數 Int32[] pageNumbers——一組頁碼。使用此參數時，僅會渲染那些頁面。此參數是通用的，適用於所有支援頁面的格式；在 Spreadsheet formats family 中，它具體表示要檢視的工作表編號。

請注意，頁碼（以及工作表編號）是 從 1 開始 的，而非從 0 開始。

以下範例示範在一個包含 3 個工作表的試算表中，將第 1 與第 3 個工作表渲染為 PNG。

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

PngViewOptions pngOptions = new PngViewOptions("worksheet_{0}.png");
using (Viewer viewer = new Viewer("spreadsheet.xlsx"))
{
    viewer.View(pngOptions, 1, 3);
}

將工作表拆分為多頁

GroupDocs.Viewer 會將文件渲染為「頁」——在此「頁」指的是相對較小的矩形區域，類似於螢幕或 A4 紙的顯示範圍。另一方面，工作表可能非常龐大。例如已淘汰的 XLS 格式僅支援 最多 256 列與 65536 行，而較新的 XLSX (Office Open XML Workbook) 以及 Microsoft Excel 均支援 最多 16384 列與 1048576 行。將工作表「適配」到頁面是使用 GroupDocs.Viewer 渲染試算表的關鍵步驟。為了將工作表適配到頁面，GroupDocs.Viewer 會執行 工作表拆分——將工作表分割成多個矩形區塊，並將每個區塊放置於單獨的頁面上。共有 5 種不同的拆分方法，以下列出並說明。

重要的是——所有這些拆分方法的指定方式相同——使用特定的靜態方法（工廠方法）來建立 SpreadsheetOptions 類別的實例。

在單一頁面上渲染整個工作表

SpreadsheetOptions.ForOnePagePerSheet()

最簡單的方式——關閉拆分，並調整頁面大小以容納整個工作表的所有內容。當已知工作表尺寸較小時，此選項是理想選擇。然而，若工作表非常龐大，這種做法可能導致糟糕的結果。特別是渲染為 HTML 時，產生的 HTML 文件可能非常龐大，達到數十甚至數百 MiB，在瀏覽器中檢視會出現問題。渲染為 JPEG 時，如果寬度或高度超過 65535 像素的上限，情況會更糟。因此，請謹慎使用此模式。

依頁面分隔符拆分工作表

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel 會根據紙張大小與頁面設定（如方向與邊距）自動加入頁面分隔符。切換到「View」標籤並進入「Page Break Preview」模式時，可看到藍色線條將整個工作表區域劃分為矩形區塊，每個區塊標示為「Page 1」、「Page 2」等。這就是 Microsoft Excel 「建議」的拆分方式。

使用此方法時，GroupDocs.Viewer 會遵循 Microsoft Excel 的頁面分隔符，將工作表依同樣方式拆分。

需要說明的是，依頁面分隔符拆分 是 BaseViewOptions.SpreadsheetOptions 屬性的預設選項。因此，當建立檢視選項類別的實例時，預設已選取 [ForRenderingByPageBreaks()]。

僅渲染列印區域

SpreadsheetOptions.ForRenderingPrintArea()

除了頁面分隔符，Microsoft Excel 還有「列印區域」的概念。列印區域是工作表中一個或多個被指定為列印的儲存格範圍，列印區域之外的內容將不會被列印。要將儲存格範圍加入列印區域，請切換到「Page Layout」標籤，點擊「Print Area」按鈕，然後選擇「Set Print Area」項目（見下圖）。若要再加入其他儲存格範圍，先選取新範圍，點擊「Print Area」按鈕，然後選擇「Add to Print Area」。在「Page Break Preview」模式下，可看到所有列印區域的儲存格範圍。

渲染列印區域並依頁面分隔符拆分

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer 具備獨特功能——在單一模式下同時結合列印區域與頁面分隔符。此時，GroupDocs.Viewer 會同時考慮列印區域的所有儲存格範圍以及工作表中的頁面分隔符，並將工作表拆分為頁面。

下圖中，紅線表示列印區域，藍線表示頁面分隔符。

手動依列與欄拆分工作表

SpreadsheetOptions.ForSplitSheetIntoPages(int countRowsPerPage)
SpreadsheetOptions.ForSplitSheetIntoPages(int countRowsPerPage, int countColumnsPerPage)

有時上述任何拆分方法都不適用，或試算表格式不支援頁面分隔符與列印區域（例如基於文字的 CSV）。對於此類情況，GroupDocs.Viewer 允許手動指定每頁應包含的列數與/或欄數。簡言之，僅依列拆分與同時依列與欄拆分的差異如下圖所示。

若使用 ForSplitSheetIntoPages 的第一個重載（單一參數），則僅啟用 依列拆分。若使用第二個重載（兩個參數），則啟用 依列與欄拆分。

調整其他選項

上述內容已足以完成基本的試算表渲染，但 GroupDocs.Viewer 還提供許多非必須的額外選項，讓使用者能進一步微調渲染結果。

其中一些選項以 SpreadsheetOptions 類別的屬性形式呈現，該類別可透過檢視選項類別的 SpreadsheetOptions 屬性取得；另一些則位於所有四種渲染模式共用的抽象類別 ViewOptions 中。

渲染列與欄標題

當 MS Excel 或類似的表格處理程式開啟試算表文件時，會顯示列與欄的標題：欄以字母標示（A、B、C、AA、AB…），列以數字標示（1、2、3…、1048576）。渲染時，GroupDocs.Viewer 預設不顯示這些標題，因為它們屬於表格處理器的介面，而非文件本身。但可透過布林型別的 RenderHeadings 屬性改變此行為。預設為 false（關閉），若設為 true，則列與欄標題會出現在輸出文件中，如下圖所示。

渲染工作表格線

此選項的概念與前者非常相似。預設情況下，GroupDocs.Viewer 不會顯示儲存格之間的格線，因為格線屬於表格處理器的呈現方式，而非試算表本身。然而，使用布林型別的 RenderGridLines 屬性即可模擬 MS Excel 的行為。將 SpreadsheetOptions.RenderGridLines 設為 true，格線即會出現在輸出文件中，如下圖所示。

控制儲存格文字溢出

常見情況是文字過長，無法完整顯示於儲存格內。GroupDocs.Viewer 提供 SpreadsheetOptions.TextOverflowMode 屬性來解決此問題。TextOverflowMode 屬性的類型同名為 TextOverflowMode，是一個包含 4 個成員的列舉（enum），說明如下。

OverlayIfNextIsEmpty

預設情況下，SpreadsheetOptions.TextOverflowMode 為 OverlayIfNextIsEmpty，模仿 Microsoft Excel 的預設行為。此值允許文字溢出至相鄰儲存格，但僅在相鄰儲存格為空時才會溢出；若相鄰儲存格非空，則文字會被截斷。

上圖顯示了使用 OverlayIfNextIsEmpty 產生的 HTML 檔案。注意儲存格 B2 內的長文字被截斷，因為 C2 並非空白。而 C3 的長文字則會溢出至 D2、E2，因為這些儲存格是空的。

Overlay

TextOverflowMode.Overlay 與前者略有相似，但更為激進：長文字若超出原始儲存格邊界，無論相鄰儲存格是否有資料，都會直接溢出，且相鄰儲存格的內容會被覆寫。

上圖示範了此行為。B2 的長文字溢出至 C2、D2、E2、F2，結果 C2 與 F2 原有的文字被抹除。

HideText

TextOverflowMode.HideText 與前述 Overlay 完全相反——不會溢出，而是直接截斷超出儲存格邊界的文字，無論相鄰儲存格是否有空間。

在上圖中，即使 D3 之後有空白，C3 的文字仍被無條件截斷。

AutoFitColumn

TextOverflowMode.AutoFitColumn 透過調整欄寬來容納文字。無論儲存格內文字多長，所在欄的寬度都會自動擴展，以完整顯示字串。

上圖展示了此效果。當然，若文字過長，頁面寬度會變得非常寬，導致水平捲動不便。

渲染隱藏的列與欄

Microsoft Excel 以及其他表格處理器允許隱藏特定的列與欄。預設情況下，GroupDocs.Viewer 不會渲染這些隱藏的列與欄，但可透過將 ViewOptions.SpreadsheetOptions.RenderHiddenRows 與 ViewOptions.SpreadsheetOptions.RenderHiddenColumns 設為 true，在渲染為 HTML、PDF、PNG 或 JPEG 時顯示隱藏的列與欄。

渲染隱藏的工作表

與前述的隱藏列與欄類似，試算表檔案也可能包含一個或多個隱藏的工作表。預設情況下，GroupDocs.Viewer 不會渲染這些隱藏工作表。但可使用 RenderHiddenPages 屬性，將其值設為 true 以顯示。需要說明的是，RenderHiddenPages 位於共用的抽象類別 BaseViewOptions，而非 SpreadsheetOptions。

跳過空的列與欄

某些試算表「稀疏」——包含大量空白儲存格，會佔用過多空間。GroupDocs.Viewer 提供跳過空列與空欄的功能。啟用此功能後，空的列與/或欄會從最終的 HTML、PDF、PNG、JPEG 中排除。布林屬性 SpreadsheetOptions.SkipEmptyRows 與 SpreadsheetOptions.SkipEmptyColumns 控制此行為。

上圖顯示同時啟用了 SkipEmptyRows 與 SkipEmptyColumns。

渲染或隱藏儲存格註解

試算表中的儲存格可能帶有註解，預設情況下 GroupDocs.Viewer 會全部渲染。但可透過 BaseViewOptions.RemoveComments 屬性將其設為 true，以不渲染任何註解。請注意，此屬性位於 BaseViewOptions 類別，而非 SpreadsheetOptions。

上圖示範了使用預設選項將帶有註解的 XLSX 檔案渲染為 PNG——E2 儲存格的註解出現在最終的 PNG 中。

在輸出 PDF 頁面中設定工作表邊距

將工作表渲染為 PDF 時，可控制頁面邊距——即頁面邊框與內容之間的距離（以公分為單位）。有四個屬性分別控制上、右、下、左邊距：

• SpreadsheetOptions.TopMargin
• SpreadsheetOptions.RightMargin
• SpreadsheetOptions.BottomMargin
• SpreadsheetOptions.LeftMargin

預設這四個屬性皆為負值，表示使用 GroupDocs.Viewer 的預設邊距。但可顯式設定正值。需強調的是，頁面邊距僅在目標格式為 PDF 時生效。

以下程式碼示範建立 PdfViewOptions，設定四個邊距，並渲染文件：

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

PdfViewOptions pdfViewOptions = new PdfViewOptions("Output.pdf");
pdfViewOptions.SpreadsheetOptions = SpreadsheetOptions.ForOnePagePerSheet();
pdfViewOptions.SpreadsheetOptions.TopMargin = 2;
pdfViewOptions.SpreadsheetOptions.BottomMargin = 4;
pdfViewOptions.SpreadsheetOptions.LeftMargin = 8;
pdfViewOptions.SpreadsheetOptions.RightMargin = 0;

using (var viewer = new Viewer("spreadsheet.xlsx"))
{
    viewer.View(pdfViewOptions);
}

以下圖片展示了結果：

結論

試算表格式相當複雜，文件的內容類型與長度差異極大。許多情況下，僅使用預設選項無法將複雜的試算表文件渲染為目標格式，這也是為什麼 GroupDocs.Viewer 提供如此完整的屬性集合；透過這些屬性，每位使用者都能依自己的需求微調渲染結果。

相關參考

• Render Excel and Apple Numbers spreadsheets as HTML, PDF, and image files
• Split a worksheet into pages
• Specify spreadsheet rendering options

取得免費試用

您可從 releases.groupdocs.com 下載 GroupDocs.Viewer for .NET 的免費試用版。亦可前往 此處 取得臨時授權，以在無限制的情況下體驗所有功能與特性。