Работа с электронными таблицами в GroupDocs.Viewer for .NET

Overview

Spreadsheet documents — это документы, содержащие данные в табличной форме — в виде строк и столбцов. Их также называют рабочими книгами. Существует множество форматов электронных таблиц — Office Open XML (например, XLSX, XLSM и др.), Microsoft Excel Binary File Format (XLS, XLT), OpenDocument Spreadsheet (ODS, FODS, OTS), текстовые форматы с разделителями (CSV, TSV и др.) и т.д. Все они образуют так называемое семейство форматов электронных таблиц. GroupDocs.Viewer поддерживает почти все форматы электронных таблиц при импорте и позволяет рендерить (конвертировать) их в HTML, PDF, PNG и JPEG. В этой статье объясняется, как это сделать, какие параметры доступны и когда и почему их следует использовать.

Rendering a workbook, opened in MS Excel, to the HTML format

Basic usage

Прежде всего нужно поговорить о параметрах. В публичном API существует отдельный класс: SpreadsheetOptions в пространстве имен GroupDocs.Viewer.Options. Этот класс специально предназначен для настройки рендеринга семейства форматов электронных таблиц. Он доступен для всех четырёх вариантов просмотра через свойство SpreadsheetOptions у соответствующего класса опций:

HtmlViewOptions.SpreadsheetOptions — при рендеринге электронных таблиц в HTML,
PdfViewOptions.SpreadsheetOptions — при рендеринге электронных таблиц в PDF,
PngViewOptions.SpreadsheetOptions — при рендеринге электронных таблиц в PNG,
JpgViewOptions.SpreadsheetOptions — при рендеринге электронных таблиц в JPEG.

Если параметр не указан явно, свойство SpreadsheetOptions получает значение по умолчанию — экземпляр класса SpreadsheetOptions, о котором будет рассказано ниже.

На первый взгляд рендеринг электронных таблиц с GroupDocs.Viewer предельно прост и аналогичен работе с другими форматами — создаёте экземпляр ViewOptions, создаёте объект Viewer с указанием входного файла таблицы и вызываете метод Viewer.View(viewOptions). Ниже приведён пример кода, демонстрирующий рендеринг одного входного файла таблицы во все четыре формата вывода: 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);
}

Теперь поговорим о листах (worksheets). У каждой таблицы как минимум один лист. В большинстве программ для работы с таблицами, таких как Microsoft Excel, листы отображаются в виде вкладок. Некоторые форматы таблиц могут содержать только один лист; к таким относятся, например, все текстовые форматы с разделителями (CSV, TSV и др.).

По умолчанию GroupDocs.Viewer рендерит все листы внутри заданной таблицы. Но это поведение можно изменить. Метод Viewer.View() имеет перегрузку, принимающую массив номеров страниц в качестве второго параметра — Int32[] pageNumbers. При использовании этого параметра будут отрисованы только указанные страницы. Параметр универсален и применяется ко всем поддерживаемым форматам, у которых есть страницы, но в контексте семейства форматов электронных таблиц он обозначает именно номера листов для просмотра.

Обратите внимание, что нумерация страниц и листов начинается с 1, а не с 0.

Ниже пример, показывающий, как отрендерить 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);
}

Splitting worksheets into pages

GroupDocs.Viewer рендерит документы постранично, где под страницей подразумевается некоторый прямоугольный участок небольшого размера, сравнимый с областью отображения или листом формата A4. С другой стороны, листы могут быть очень большими. Например, устаревший формат XLS поддерживает максимум 256 столбцов и 65 536 строк, тогда как более новый формат XLSX (Office Open XML Workbook) и Microsoft Excel поддерживают до 16 384 столбцов и 1 048 576 строк. «Вмещение» листов в страницы — ключевая часть рендеринга таблиц с GroupDocs.Viewer. Чтобы разместить лист на странице(ах), GroupDocs.Viewer выполняет разбиение листа — лист делится на несколько прямоугольных фрагментов, каждый из которых помещается на отдельную страницу. Существует 5 разных методов разбиения, они перечислены и описаны ниже.

Важно — все эти методы разбиения задаются одинаковым способом — вызовом конкретного статического (фабричного) метода, который создаёт экземпляр класса SpreadsheetOptions.

Render whole worksheet on one page

SpreadsheetOptions.ForOnePagePerSheet()

Самый простой способ — отключить разбиение и подобрать размер страницы так, чтобы он вместил всё содержимое листа. Это хороший вариант, когда заранее известно, что лист небольшой. Однако если лист действительно большой, такой подход может привести к ужасным результатам. В частности, при рендеринге в HTML полученный документ может стать огромным, измеряться десятками или даже сотнями MiB, что создаёт проблемы при просмотре в браузерах. При рендеринге в JPEG ситуация может ухудшиться, если ширина или высота превысят максимальный предел — 65535 пикселей. Поэтому используйте этот режим осознанно.

Split worksheet by page breaks

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel автоматически вставляет разрывы страниц в зависимости от размера листа и настроек страницы (ориентация, поля). Если переключиться на вкладку «View» и выбрать режим «Page Break Preview», можно увидеть синие линии, делящие лист на прямоугольные фрагменты, каждый из которых помечен как «Page 1», «Page 2» и т.д. Именно так Microsoft Excel «предлагает» разбить лист на страницы.

С помощью этого метода GroupDocs.Viewer следует рекомендациям Excel и разбивает листы согласно разрывам страниц, как это делает сама Excel.

Стоит отметить, что эта опция — разбиение листа по разрывам страниц — является опцией по умолчанию свойства BaseViewOptions.SpreadsheetOptions. Поэтому при создании экземпляра класса опций просмотра автоматически выбирается вариант [ForRenderingByPageBreaks()].

Render only print area

SpreadsheetOptions.ForRenderingPrintArea()

Помимо разрывов страниц, в Excel существует понятие «Область печати» (Print Area). Область печати — это один или несколько диапазонов ячеек, предназначенных для печати; всё, что находится за её пределами, не печатается. Чтобы добавить диапазон в область печати, откройте вкладку «Page Layout», нажмите кнопку «Print Area» и выберите пункт «Set Print Area». Чтобы добавить ещё один диапазон, выделите его, снова нажмите «Print Area» и выберите «Add to Print Area». В режиме «Page Break Preview» видно все диапазоны, входящие в область печати.

Render print area and split by page breaks

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer обладает уникальной возможностью — совместить область печати и разрывы страниц в одном режиме. В этом случае учитываются как все диапазоны области печати, так и разрывы страниц, и они одновременно применяются для разбиения листа на страницы.

На скриншоте ниже красная линия обозначает область печати, а синяя — разрывы страниц.

Render print area and split by page breaks

Split worksheet into pages manually by rows and columns

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

Иногда ни один из описанных выше методов разбиения не подходит, либо формат таблицы не поддерживает разрывы страниц и области печати (например, текстовый CSV). В таких случаях GroupDocs.Viewer позволяет вручную задать количество строк и/или столбцов, которые должны помещаться на каждой странице. Кратко: разница между разбиением только по строкам и разбиением по строкам + столбцам иллюстрирована на скриншоте ниже.

Если используется первая перегрузка метода ForSplitSheetIntoPages с одним параметром, включается разбиение только по строкам. Если используется вторая перегрузка с двумя параметрами, включается разбиение по строкам и столбцам.

Split worksheet into pages manually by rows and columns

Adjusting additional options

Всё описанное выше — это базовый набор, достаточный для рендеринга таблиц с GroupDocs.Viewer. Однако существует множество дополнительных параметров, которые не обязательны, но позволяют пользователю ещё точнее настроить результат рендеринга.

Некоторые из этих параметров представлены в виде свойств класса SpreadsheetOptions, доступного через свойство SpreadsheetOptions у класса опций просмотра. Другие находятся в абстрактном классе ViewOptions, общим для всех четырёх режимов рендеринга.

Render row and column headings

Когда MS Excel (или аналогичная программа) открывает файл таблицы, она отображает заголовки столбцов и строк: столбцы обозначаются буквами (A, B, C, AA, AB …), а строки — номерами (1, 2, 3 …, 1048576). По умолчанию GroupDocs.Viewer не выводит эти заголовки, так как они являются частью интерфейса программы, а не самого документа. Это поведение можно изменить с помощью свойства RenderHeadings типа bool. По умолчанию оно отключено (false), но при включении (true) заголовки строк и столбцов появятся в результирующем документе, как показано на скриншоте.

Render worksheet gridlines

Принцип действия этой опции аналогичен предыдущей. По умолчанию GroupDocs.Viewer не отображает линии сетки между ячейками, поскольку они не являются частью самой таблицы, а лишь способом визуального представления данных в конкретном редакторе. С помощью свойства RenderGridLines типа bool можно имитировать поведение MS Excel. Установив true для свойства SpreadsheetOptions.RenderGridLines, линии сетки появятся в выводимом документе, как показано на скриншоте.

Control cell text overflow

Часто встречается ситуация, когда текст в ячейке не помещается в её границы. Как отобразить такой текст? GroupDocs.Viewer предоставляет специальное свойство SpreadsheetOptions.TextOverflowMode для решения этой задачи. Свойство TextOverflowMode имеет тип с тем же именем — TextOverflowMode, представляющий перечисление с четырьмя возможными значениями, описанными ниже.

OverlayIfNextIsEmpty

По умолчанию SpreadsheetOptions.TextOverflowMode имеет значение OverlayIfNextIsEmpty, которое имитирует поведение Microsoft Excel. Текст может «выходить» за пределы ячейки в соседние ячейки, но только если они пусты. Если соседняя ячейка содержит данные, текст обрезается.

На скриншоте показан HTML‑файл, полученный из XLSX с параметром OverlayIfNextIsEmpty. Обратите внимание на ячейку B2 — текст в ней обрезан, потому что ячейка C2 не пуста. Ячейка C3, однако, тоже содержит длинный текст, который «вытекает» в ячейки D2 и E2, так как они пусты.

Overlay

Значение Overlay работает схоже, но более агрессивно: длинный текст, не помещающийся в исходную ячейку, всегда «вытекает» в соседние ячейки, независимо от их содержимого, стирая при этом любые данные в этих ячейках.

На скриншоте видно, как текст из ячейки B2 заполняет ячейки C2, D2, E2, F2. В результате оригинальные данные в ячейках C2 и F2 удаляются.

HideText

Режим TextOverflowMode.HideText работает противоположно Overlay — текст, который не помещается в границы своей ячейки, просто обрезается, независимо от наличия свободного места в соседних ячейках.

На скриншоте видно, что в ячейке C3 текст обрезан, хотя рядом в D3 и дальше есть свободное место.

AutoFitColumn

Значение AutoFitColumn решает проблему иначе — увеличивает ширину столбца так, чтобы в нём поместился весь текст. Поэтому независимо от длины текста в конкретной ячейке, ширина столбца, в котором она находится, будет расширена до полного отображения строки.

Скриншот демонстрирует работу этого режима. Учтите, что такой подход может быть непрактичным, если текст в ячейках очень длинный — страница станет чрезмерно широкой, вызывая неудобную горизонтальную прокрутку.

Render hidden rows and columns

Microsoft Excel и другие редакторы позволяют скрывать отдельные строки и столбцы. По умолчанию GroupDocs.Viewer такие строки и столбцы не рендерит, но это поведение можно изменить. Свойства ViewOptions.SpreadsheetOptions.RenderHiddenRows и ViewOptions.SpreadsheetOptions.RenderHiddenColumns, если установить в true, заставят отображать скрытые строки и столбцы в результирующем файле при рендеринге в HTML, PDF, PNG или JPEG.

Render hidden worksheets

Подобно скрытым строкам и столбцам, файл таблицы может содержать скрытые листы. По умолчанию GroupDocs.Viewer их не отображает. Это можно изменить, установив свойство RenderHiddenPages в true. Обратите внимание, что в отличие от ранее описанных свойств, RenderHiddenPages находится не в SpreadsheetOptions, а в абстрактном классе BaseViewOptions, общим для всех вариантов просмотра.

Skip empty rows and columns

Некоторые таблицы «разреженные» — в них много пустых ячеек, что может занимать лишнее место. GroupDocs.Viewer позволяет пропускать пустые строки и столбцы при рендеринге. Если эта функция включена, пустые строки и/или столбцы исключаются из итогового HTML, PDF, PNG и JPEG. За это отвечают булевы свойства SpreadsheetOptions.SkipEmptyRows и SpreadsheetOptions.SkipEmptyColumns.

Скриншот показывает, что оба свойства — SkipEmptyRows и SkipEmptyColumns — включены.

Render or hide cell comments

Ячейки в таблице могут содержать комментарии, и по умолчанию GroupDocs.Viewer выводит их все. Это можно отключить, используя свойство BaseViewOptions.RemoveComments: при установке true комментарии не будут рендериться. Учтите, что данное свойство находится в классе BaseViewOptions, а не в SpreadsheetOptions.

На скриншоте показан рендеринг XLSX‑файла с комментариями в PNG при настройках по умолчанию — комментарий к ячейке E2 присутствует в итоговом изображении.

Set worksheet margins in the output PDF pages

При рендеринге листов в PDF можно управлять полями страниц — расстоянием в сантиметрах от границы страницы до содержимого. Существует четыре свойства для задания верхнего, правого, нижнего и левого полей:

По умолчанию все эти свойства имеют отрицательные значения, что означает применение полей, заданных по умолчанию в 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);
}

Результат показан на изображении ниже:

Set worksheet margins in the output PDF pages

Conclusion

Форматы электронных таблиц довольно сложны, а документы могут иметь очень разное содержание по типу и объёму. Во многих случаях невозможно корректно отрендерить сложный документ таблицы в нужный формат, используя только параметры по умолчанию, поэтому GroupDocs.Viewer предоставляет обширный набор свойств; с их помощью каждый пользователь сможет настроить рендеринг под свои требования.

Get a free trial

Вы можете скачать бесплатную пробную версию GroupDocs.Viewer для .NET с сайта releases.groupdocs.com. Также можно получить временную лицензию для полного доступа ко всем функциям без ограничений — по ссылке here.

Overview#

Basic usage#

Splitting worksheets into pages#

Render whole worksheet on one page#

Split worksheet by page breaks#

Render only print area#

Render print area and split by page breaks#

Split worksheet into pages manually by rows and columns#

Adjusting additional options#

Render row and column headings#

Render worksheet gridlines#

Control cell text overflow#

OverlayIfNextIsEmpty#

Overlay#

HideText#

AutoFitColumn#

Render hidden rows and columns#

Render hidden worksheets#

Skip empty rows and columns#

Render or hide cell comments#

Set worksheet margins in the output PDF pages#

Conclusion#

See Also#

Get a free trial#