Работа с электронными таблицами в 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

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

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

HideText

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

На скриншоте выше это видно на примере ячейки «C3»: хотя рядом есть свободные ячейки «D3» и далее, текст всё равно обрезается.

AutoFitColumn

Значение TextOverflowMode.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#