Робота з електронними таблицями у GroupDocs.Viewer для .NET

Overview

Документи електронних таблиць — це документи, що містять дані у табличній формі — у рядках і стовпцях. Їх також називають книжками (workbooks). Існує безліч форматів документів електронних таблиць — Office Open XML (наприклад XLSX, XLSM тощо), Microsoft Excel Binary File Format (XLS, XLT), OpenDocument Spreadsheet (ODS, FODS, OTS), текстові формати з розділювачами (CSV, TSV тощо) та інші. Усі вони утворюють так звану сімейство форматів електронних таблиць. GroupDocs.Viewer підтримує майже всі формати електронних таблиць під час імпортy та дозволяє рендерити (конвертувати) їх у 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). У наведеному нижче прикладі коду продемонстровано рендеринг одного вхідного файлу електронної таблиці у всі 4 формати виводу: 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 різних методів, які наведено і описано нижче.

Важливо — всі ці методи розділення вказуються однаковим способом — через конкретний статичний (factory) метод, що створює інстанс класу SpreadsheetOptions.

Render whole worksheet on one page

SpreadsheetOptions.ForOnePagePerSheet()

Найпростіший спосіб — вимкнути розділення і підлаштувати розмір сторінки так, щоб умістити весь листок. Це підходить, коли відомо, що листок невеликий. Однак, якщо листок дійсно великий, такий підхід може призвести до поганих результатів. Зокрема, при рендерингу у HTML отриманий документ може бути величезним — десятки або навіть сотні MiB, що ускладнює його перегляд у веб‑браузерах. При рендерингу у JPEG ситуація може бути ще гіршою, якщо ширина або висота перевищать максимум у 65 535 пікселів. Тому використовуйте цей режим свідомо.

Split worksheet by page breaks

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel автоматично додає розриви сторінок (page breaks) згідно з розміром паперу та налаштуваннями сторінки (орієнтація, поля). Якщо перейти на вкладку «View» і вибрати режим «Page Break Preview», можна побачити сині лінії, які розбивають листок на прямокутні частини, кожна з яких підписана «Page 1», «Page 2» тощо. Так Excel «пропонує» розбивати листок на сторінки.

За допомогою цього методу GroupDocs.Viewer слідує за Excel і розбиває листки відповідно до розривів сторінок.

Слід зазначити, що ця опція — розбивка листка за розривами сторінок — є типовою опцією властивості BaseViewOptions.SpreadsheetOptions. Тобто при створенні інстансу класу параметрів перегляду за замовчуванням вибрано [ForRenderingByPageBreaks()].

Render only print area

SpreadsheetOptions.ForRenderingPrintArea()

Окрім розривів сторінок, у Excel існує концепція «Print Area». Це один або декілька діапазонів клітинок, які позначені для друку; вміст поза цим діапазоном не друкується. Щоб додати діапазон до Print Area, відкрийте вкладку «Page Layout», натисніть кнопку «Print Area» і оберіть пункт «Set Print Area». Щоб додати ще один діапазон, виділіть його, знову натисніть «Print Area» і виберіть «Add to Print Area». У режимі «Page Break Preview» видно всі діапазони Print Area.

Render print area and split by page breaks

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer має унікальну можливість — одночасно застосовувати Print Area і розриви сторінок. У цьому випадку враховуються і діапазони Print Area, і розриви сторінок, і вони одночасно впливають на розбиття листка.

На скріншоті червона лінія позначає Print Area, синя — розриви сторінок.

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)

Іноді жоден з попередніх методів не підходить, або файл таблиці не підтримує розриви сторінок і Print Area (наприклад, CSV). У таких випадках GroupDocs.Viewer дозволяє вручну вказати кількість рядків і/або стовпців, які мають бути на кожній сторінці. На скріншоті нижче показано різницю між розбиттям лише по рядках і розбиттям по рядках і стовпцях.

Якщо використано перший перегружений метод ForSplitSheetIntoPages з одним параметром, включається лише розбиття по рядках. Якщо використано другий перегружений метод з двома параметрами — розбиття по рядках і стовпцях.

Split worksheet into pages manually by rows and columns

Adjusting additional options

Все вищевикладене — це сутність і достатньо для рендерингу електронних таблиць за допомогою GroupDocs.Viewer. Проте існує безліч додаткових параметрів, які не є обов’язковими, але дозволяють користувачам ще точніше налаштувати результат.

Деякі з цих параметрів представлено у вигляді властивостей класу SpreadsheetOptions, який доступний через властивість SpreadsheetOptions у класі параметрів перегляду. Інші розташовані у абстрактному класі ViewOptions, спільному для усіх 4 режимів рендерингу.

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 можна імітувати поведінку Excel. Присвоївши true властивості SpreadsheetOptions.RenderGridLines, лінії сітки будуть присутні у вихідному документі, як показано нижче.

Control cell text overflow

Часто трапляється, що текст не вміщується у межі клітинки. Як це правильно відобразити? GroupDocs.Viewer пропонує спеціальну властивість SpreadsheetOptions.TextOverflowMode для вирішення цієї проблеми. Властивість має тип TextOverflowMode — перелік (enum) з 4-ма можливими значеннями, описаними нижче.

OverlayIfNextIsEmpty

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

Скріншот демонструє цей підхід. Хоча він практичний, у випадку дуже довгих текстів сторінка може стати надто широкою, що призведе до нав’язливого горизонтального скролінгу.

Render hidden rows and columns

Microsoft Excel та інші процесори дозволяють приховувати окремі рядки і стовпці. За замовчуванням GroupDocs.Viewer їх не рендерить, але цю поведінку можна змінити. Встановивши у true властивості ViewOptions.SpreadsheetOptions.RenderHiddenRows та ViewOptions.SpreadsheetOptions.RenderHiddenColumns, ви отримаєте у вихідному файлі приховані рядки та стовпці при рендерингу у HTML, PDF, PNG або JPEG.

Render hidden worksheets

Подібно до прихованих рядків і стовпців, файл електронної таблиці може містити один або кілька прихованих листків. За замовчуванням GroupDocs.Viewer їх не рендерить. Це можна змінити, встановивши у true властивість RenderHiddenPages. Зауважте, що на відміну від попередніх властивостей, 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» присутній у результатному PNG‑файлі.

Set worksheet margins in the output PDF pages

Під час рендерингу листків у PDF можна керувати полями сторінки — відстанню в сантиметрах від краю сторінки до вмісту. Є 4 властивості для керування верхнім, правим, нижнім і лівим полем:

За замовчуванням усі 4 властивості мають від’ємні значення, що означає застосування полів за замовчуванням GroupDocs.Viewer. Проте їх можна задати явно. Варто наголосити, що поля застосовуються лише коли цільовий формат — PDF.

Нижче наведено приклад коду, який створює PdfViewOptions, задає всі 4 поля та рендерить документ:

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. Також можна отримати тимчасову ліцензію для повного тестування всіх можливостей без обмежень тут.

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#