在 GroupDocs.Viewer for .NET 中使用电子表格

概述

Spreadsheet documents 是以表格形式——行和列——包含数据的文档。它们也被称为 workbooks（工作簿）。电子表格文档有许多格式——Office Open XML（如 XLSX、XLSM 等）、Microsoft Excel 二进制文件格式（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）中，工作表表现为 标签页。某些电子表格格式可能只有单个工作表；例如所有基于文本的分隔符分割格式（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 还有 “Print Area”（打印区域）概念。打印区域实际上是工作表中一个或多个用于打印的单元格范围，打印区域之外的内容根本不会被打印。要将某个单元格范围加入打印区域，请转到 “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 个可能的取值，下面依次说明。

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 相反——它会直接截断超出单元格边界的文本，无论相邻单元格是否有空余空间。

在上图中，单元格 C3 的文本被截断，即使相邻的 D3 等单元格有空余。

AutoFitColumn

TextOverflowMode.AutoFitColumn 通过另一种方式解决问题——自动增宽所在列以容纳文本。因此，无论单元格内的文本多长，所在列的宽度都会被扩大以完整显示该字符串。

上图展示了该效果。当然，在文本极长的情况下，这种做法可能导致页面异常宽，出现令人不适的水平滚动条。

渲染隐藏的行和列

Microsoft Excel 等表格处理器允许隐藏特定的行或列。默认情况下，GroupDocs.Viewer 不会渲染这些隐藏的行列，但可以通过将 ViewOptions.SpreadsheetOptions.RenderHiddenRows 和 ViewOptions.SpreadsheetOptions.RenderHiddenColumns 属性设为 true，在渲染为 HTML、PDF、PNG 或 JPEG 时显示隐藏的行列。

渲染隐藏的工作表

与上述隐藏行列类似，电子表格文件也可能包含一个或多个隐藏的工作表。默认情况下，GroupDocs.Viewer 不会渲染这些隐藏工作表。但可以通过将 RenderHiddenPages 属性设为 true 来改变此行为。需要说明的是，RenderHiddenPages 不在 SpreadsheetOptions 中，而是位于所有视图选项共用的抽象类 BaseViewOptions 中。

跳过空行和空列

有些电子表格非常“稀疏”，包含大量空白区域，占用过多空间。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 的免费试用版。也可以通过 此处 获取临时许可证，免费试用所有功能和特性，无任何限制。