Работа с электронными таблицами в GroupDocs.Viewer для .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);
}

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

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

Обратите внимание, что нумерация страниц в общем случае и нумерация листов в частности являются 1‑основанными, а не 0‑основанными, то есть нумерация начинается с «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 столбцов и 65536 строк, тогда как более новый формат XLSX (Office Open XML Workbook) и Microsoft Excel поддерживают до 16384 столбцов и 1048576 строк. «Вмещение» листов в страницы — ключевая часть отрисовки таблиц с помощью 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 следует рекомендациям Microsoft Excel и разделяет листы согласно разрывам страниц, как это делает сам 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 обладает уникальной возможностью — совмещать область печати и разрывы страниц в одном режиме. В этом случае 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 типа bool. По умолчанию оно отключено (false), а при установке в true заголовки строк и столбцов появятся в результирующем документе, как показано на скриншоте ниже.

Отрисовка линий сетки листа

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

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

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

OverlayIfNextIsEmpty

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

На скриншоте выше показан HTML‑файл, полученный из XLSX с этим значением. Обратите внимание на ячейку «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‑формате можно управлять полями страниц — отступами в сантиметрах от границы страницы до содержимого. Существует 4 свойства для управления верхним, правым, нижним и левым полями:

• 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 → Отрисовка таблиц Excel и Apple Numbers в HTML, PDF и изображения
• Split a worksheet into pages → Разделение листа на страницы
• Specify spreadsheet rendering options → Указание параметров отрисовки таблиц

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

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