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

Огляд

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

Базове використання

Перш за все треба поговорити про параметри. У публічному 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», а не з «0».

Нижче наведено приклад, як рендерити 1‑й і 3‑й листок у PNG у таблиці, що містить 3 листки.

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 рендерить документи у вигляді сторінок, під сторінкою розуміємо деяку прямокутну область відносно малого розміру, порівнянну з областю дисплея або листа А4. З іншого боку, листки можуть бути дуже великими. Зокрема, застарілий формат 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 має унікальну можливість — поєднання області друку та розривів сторінок в одному режимі. У цьому випадку GroupDocs.Viewer одночасно враховує всі діапазони області друку та розриви сторінок у листку і застосовує їх для розбиття листка на сторінки.

На наведеному скріншоті червона лінія позначає область друку, а синя — розриви сторінок.

Render print area and split by page breaks

Ручне розбиття листка на сторінки за рядками та стовпцями

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

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

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

Split worksheet into pages manually by rows and columns

Налаштування додаткових параметрів

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

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

Рендерити заголовки рядків і стовпців

Коли 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 має тип з такою ж назвою, який є enum‑ом з 4 можливими значеннями, описаними нижче.

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

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

Рендерити приховані рядки та стовпці

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 властивості для керування верхнім, правим, нижнім і лівим полем:

За замовчуванням усі ці 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

Висновок

Формати електронних таблиць досить складні, а документи можуть мати дуже різноманітний вміст різної довжини та типу. У багатьох випадках неможливо коректно рендерити складний документ електронної таблиці у певний формат за допомогою параметрів за замовчуванням, тому GroupDocs.Viewer надає такий широкий набір властивостей; завдяки їм кожен користувач зможе налаштувати рендеринг під свої потреби.

Дивіться також

Отримати безкоштовну пробну версію

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

Огляд#

Базове використання#

Розбиття листків на сторінки#

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

Розбивати листок за розривами сторінок#

Рендерити лише область друку#

Рендерити область друку та розбивати за розривами сторінок#

Ручне розбиття листка на сторінки за рядками та стовпцями#

Налаштування додаткових параметрів#

Рендерити заголовки рядків і стовпців#

Рендерити сітку листка#

Керування переповненням тексту в клітинці#

OverlayIfNextIsEmpty#

Overlay#

HideText#

AutoFitColumn#

Рендерити приховані рядки та стовпці#

Рендерити приховані листки#

Пропускати порожні рядки та стовпці#

Рендерити або приховувати коментарі в клітинках#

Встановлення полів листка у вихідних PDF‑сторінках#

Висновок#

Дивіться також#

Отримати безкоштовну пробну версію#