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

Обзор

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. В этой статье объясняется, как это сделать, какие параметры доступны и когда и почему их следует использовать.

Базовое использование

Прежде всего нужно поговорить о параметрах. В публичном 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);
}

Разбиение листов на страницы

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.

Рендерить весь лист на одной странице

SpreadsheetOptions.ForOnePagePerSheet()

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

Разбивать лист по разрывам страниц

SpreadsheetOptions.ForRenderingByPageBreaks()

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

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

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

Рендерить только область печати

SpreadsheetOptions.ForRenderingPrintArea()

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

Рендерить область печати и разбивать по разрывам страниц

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

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 …). По умолчанию GroupDocs.Viewer не выводит эти заголовки, так как они являются частью интерфейса программы, а не самого документа. Это можно изменить с помощью свойства RenderHeadings типа bool. По умолчанию оно отключено (false), но при включении (true) заголовки строк и столбцов появятся в результирующем документе, как показано на скриншоте.

Рендерить линии сетки листа

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

Управление переполнением текста в ячейках

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

OverlayIfNextIsEmpty

По умолчанию SpreadsheetOptions.TextOverflowMode имеет значение OverlayIfNextIsEmpty, что имитирует поведение 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 решает проблему иначе — увеличивает ширину столбца, чтобы вместить весь текст ячейки. Поэтому независимо от длины текста ширина соответствующего столбца будет расширена.

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

Рендерить скрытые строки и столбцы

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

Рендерить скрытые листы

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

Пропускать пустые строки и столбцы

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

На скриншоте видно, что оба свойства включены.

Рендерить или скрывать комментарии ячеек

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

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

Установка полей листа в выходных 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

Получить бесплатную пробную версию

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