Práce s tabulkovými kalkulátory v GroupDocs.Viewer pro .NET

Přehled

Spreadsheet documents jsou dokumenty, které obsahují data v tabulkové podobě — v řádcích a sloupcích. jsou také známé jako sešity. Existuje mnoho formátů tabulkových dokumentů — Office Open XML (např. XLSX, XLSM, atd.), Microsoft Excel Binary File Format (XLS, XLT), OpenDocument Spreadsheet (ODS, FODS, OTS), textové formáty oddělené značkou (CSV, TSV atd.) a další. Všechny patří do takzvané rodiny formátů tabulek. GroupDocs.Viewer podporuje téměř všechny formáty tabulek při importu a umožňuje je převádět (renderovat) do HTML, PDF, PNG a JPEG. Tento článek vysvětluje, jak to provést, jaké možnosti jsou k dispozici a kdy a proč je použít.

Základní použití

Nejprve je potřeba seznámit se s možnostmi. Ve veřejném API existuje samostatná třída: SpreadsheetOptions v namespace GroupDocs.Viewer.Options. Tato třída je určena speciálně pro nastavení renderování rodiny formátů tabulek. Je přístupná ze všech čtyř možností zobrazení pomocí vlastnosti SpreadsheetOptions:

• HtmlViewOptions.SpreadsheetOptions při renderování tabulkového dokumentu do HTML,
• PdfViewOptions.SpreadsheetOptions při renderování tabulkového dokumentu do PDF,
• PngViewOptions.SpreadsheetOptions při renderování tabulkového dokumentu do PNG,
• JpgViewOptions.SpreadsheetOptions při renderování tabulkového dokumentu do JPEG.

Pokud není tato vlastnost zadána explicitně, má SpreadsheetOptions implicitní výchozí hodnotu instance třídy SpreadsheetOptions, o níž se dozvíte později v tomto článku.

Na první pohled je renderování tabulkového dokumentu pomocí GroupDocs.Viewer naprosto jednoduché a podobné jako u všech ostatních formátů — vytvoříte instanci ViewOptions, vytvoříte instanci Viewer s konkrétním vstupním tabulkovým souborem a zavoláte metodu Viewer.View(viewOptions). Následující ukázkový kód demonstruje renderování jediného vstupního souboru tabulky do všech čtyř výstupních formátů: HTML, PDF, PNG a JPEG. Všimněte si, že kromě vytvoření instancí tříd možností neprobíhá žádné další ladění týkající se tabulek, takže všechny možnosti tabulky mají výchozí hodnoty.

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);
}

Nyní se podíváme na listy. Každá tabulka má alespoň jeden list. Většina tabulkových programů, jako je Microsoft Excel, představuje listy jako záložky. Některé formáty tabulek mohou obsahovat pouze jediný list — to platí například pro všechny textové formáty oddělené značkou (CSV, TSV atd.).

Ve výchozím nastavení GroupDocs.Viewer vykresluje všechny listy v zadané tabulce. Toto chování lze změnit. Metoda Viewer.View() má přetížení, které přijímá sadu čísel stránek jako druhý parametr — Int32[] pageNumbers. Pokud je tento parametr použit, budou vykresleny pouze uvedené stránky. Tento parametr je univerzální a používá se pro všechny podporované formáty, které mají stránky, ale v kontextu rodiny tabulkových formátů představuje právě čísla listů, která se mají zobrazit.

Všimněte si, že číslování stránek (obecně) i listů (specificky) je založeno na čísle 1, nikoli 0, takže číslování začíná od „1“, ne od „0“.

Níže uvedený příklad ukazuje, jak vykreslit 1. a 3. list do PNG v tabulce, která má 3 listy.

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);
}

Rozdělení listů na stránky

GroupDocs.Viewer vykresluje dokumenty na stránky, kde pod „stránkou“ rozumíme obdélníkovou oblast relativně malé velikosti, srovnatelnou s plochou displeje nebo papíru formátu A4. Na druhou stranu mohou být listy velmi velké. Například již zastaralý formát XLS podporuje maximálně 256 sloupců a 65 536 řádků, zatímco novější formát XLSX (Office Open XML Workbook) a Microsoft Excel podporují až 16 384 sloupců a 1 048 576 řádků. „Umístění“ listů na stránky je klíčovou součástí renderování tabulek pomocí GroupDocs.Viewer. Aby se list vešel na stránku (nebo stránky), provádí GroupDocs.Viewer rozdělení listu — list se rozdělí na více obdélníkových úseků, z nichž každý je umístěn na samostatné stránce. Existuje 5 různých metod, které jsou uvedeny a popsány níže.

Důležité: všechny tyto metody rozdělení se specifikují stejným způsobem — použitím konkrétní statické (factory) metody, která vytvoří instanci třídy SpreadsheetOptions.

Vykreslit celý list na jedné stránce

SpreadsheetOptions.ForOnePagePerSheet()

Nejjednodušší způsob — vypnout rozdělení a nastavit velikost stránky tak, aby pojmula celý obsah listu. Toto je dobrá volba, pokud už víte, že list je malý. Pokud je list opravdu velký, může tento přístup vést k nepříjemným výsledkům. Například při renderování do HTML může vzniknout obrovský soubor o velikosti desítek nebo i stovek MiB, což může způsobit problémy při prohlížení v prohlížečích. Při renderování do JPEG může dojít k problémům, pokud šířka nebo výška překročí maximální limit 65 535 pixelů. Používejte tento režim tedy uvážlivě.

Rozdělit list podle zalomení stránek

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel sám automaticky vkládá zalomení stránek na základě velikosti papíru a nastavení stránky (orientace, okraje). Pokud přepnete na kartu Zobrazení a vyberete režim Náhled zalomení stránek, uvidíte modré čáry, které dělí celý list na obdélníkové úseky označené jako „Stránka 1“, „Stránka 2“ atd. Takto Excel „navrhuje“ rozdělení listu na stránky.

Tato metoda způsobí, že GroupDocs.Viewer následuje Excel a rozděluje listy podle těchto zalomení stránek.

Je třeba poznamenat, že tato volba — rozdělení listu podle zalomení stránek — je výchozí volbou vlastnosti BaseViewOptions.SpreadsheetOptions. Při vytvoření instance třídy možností zobrazení je tedy ve výchozím stavu automaticky vybrána metoda ForRenderingByPageBreaks().

Vykreslit jen tiskovou oblast

SpreadsheetOptions.ForRenderingPrintArea()

Kromě zalomení stránek má Microsoft Excel koncept „Tiskové oblasti“. Tisková oblast je jeden nebo více rozsahů buněk, které jsou určené k tisku; vše mimo tuto oblast se neukáže. Pro nastavení tiskové oblasti přejděte na kartu Rozvržení stránky, klikněte na tlačítko Tisková oblast a zvolte Nastavit tiskovou oblast. Pro přidání dalšího rozsahu vyberte nové buňky, znovu klikněte na Tisková oblast a zvolte Přidat do tiskové oblasti. V režimu Náhled zalomení stránek uvidíte všechny rozsahy, které tvoří tiskovou oblast.

Vykreslit tiskovou oblast a rozdělit podle zalomení stránek

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer má unikátní funkci — kombinaci tiskové oblasti a zalomení stránek v jednom režimu. V tomto případě GroupDocs.Viewer zohlední všechny rozsahy tiskové oblasti i zalomení stránek a použije je současně k rozdělení listu na stránky.

Na následujícím snímku červená čára označuje tiskovou oblast a modrá čára zalomení stránek.

Ručně rozdělit list na stránky podle řádků a sloupců

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

Někdy žádná z výše popsaných metod rozdělení není přijatelná, nebo formát tabulky nepodporuje zalomení stránek a tiskové oblasti, například textový CSV. V takových případech GroupDocs.Viewer umožňuje ručně zadat počet řádků a/nebo sloupců, které mají být na každé stránce. Rozdíl mezi rozdělením jen podle řádků a rozdělením podle řádků a sloupců je znázorněn na následujícím snímku.

Pokud je použito první přetížení metody ForSplitSheetIntoPages s jedním parametrem, zapíná se rozdělení jen podle řádků. Pokud je použito druhé přetížení se dvěma parametry, zapíná se rozdělení podle řádků i sloupců.

Nastavení dalších možností

Vše, co jsme doposud popsal, je nezbytné a postačuje pro základní renderování tabulek pomocí GroupDocs.Viewer. Existuje však řada dalších volitelných možností, které nejsou povinné, ale umožňují uživateli výsledek ještě více přizpůsobit.

Některé z těchto možností jsou reprezentovány jako vlastnosti třídy SpreadsheetOptions, která je přístupná přes vlastnost SpreadsheetOptions v třídě možností zobrazení. Další se nacházejí v abstraktní třídě ViewOptions, společné pro všechny čtyři režimy renderování.

Vykreslit popisky řádků a sloupců

Když MS Excel nebo podobný tabulkový program otevře tabulkový dokument, zobrazuje záhlaví sloupců a řádků – sloupce jsou označeny písmeny (A, B, C, AA, AB, …) a řádky čísly (1, 2, 3, …, 1048576). Při renderování GroupDocs.Viewer ve výchozím nastavení tyto záhlaví nezobrazuje, protože jsou součástí uživatelského rozhraní tabulkového procesoru, nikoli samotného dokumentu. Toto chování lze změnit pomocí vlastnosti RenderHeadings typu bool. Ve výchozím nastavení je vypnuta (false), ale pokud ji zapnete (true), budou vygenerované soubory obsahovat řádkové a sloupcové záhlaví, jak je ukázáno na snímku níže.

Vykreslit mřížku listu

Princip této možnosti je velmi podobný předchozí. Ve výchozím nastavení GroupDocs.Viewer nezobrazuje mřížku mezi buňkami, protože není součástí tabulky, ale spíše vizuální reprezentací konkrétního tabulkového procesoru. Pomocí vlastnosti RenderGridLines typu bool lze napodobit chování MS Excel. Nastavte true na SpreadsheetOptions.RenderGridLines a mřížka se objeví ve výstupním souboru, jak ukazuje následující snímek.

Řízení přetečení textu v buňce

Často se setkáte s tím, že text v buňce se nevejde do jejích hranic. Jak tento text správně zobrazit? GroupDocs.Viewer poskytuje speciální vlastnost SpreadsheetOptions.TextOverflowMode pro řešení tohoto problému. Vlastnost TextOverflowMode má typ se stejným názvem a jedná se o výčtový typ (enum) se 4 možnými hodnotami, které jsou popsány níže.

OverlayIfNextIsEmpty

Ve výchozím nastavení má SpreadsheetOptions.TextOverflowMode hodnotu OverlayIfNextIsEmpty, která napodobuje chování výchozího Microsoft Excel. Tato hodnota umožňuje textu přetéct do sousedních buněk, ale jen pokud jsou tyto buňky prázdné. Pokud nejsou, přetečení je oříznuto.

Na snímku výše je vidět HTML soubor vygenerovaný z XLSX se zapnutou hodnotou OverlayIfNextIsEmpty. V buňce „B2“ je dlouhý text, který je oříznut, protože buňka „C2“ není prázdná. Buňka „C3“ má také dlouhý text, který přesahuje do buněk „D2“ a „E2“, protože ty jsou prázdné.

Overlay

Hodnota TextOverflowMode.Overlay je podobná předchozí, ale je agresivnější: dlouhý text, který přesahuje původní buňku, vždy přetéče, bez ohledu na to, zda jsou sousední buňky prázdné. Pokud sousední buňky obsahují data, tato data jsou smazána.

Na snímku výše je ukázáno, jak to funguje. Dlouhý text z buňky „B2“ přetékl do buněk „C2“, „D2“, „E2“ a „F2“. Výsledkem je, že původní text v buňkách „C2“ a „F2“ byl smazán.

HideText

TextOverflowMode.HideText funguje opačně k režimu Overlay – místo přetečení je text prostě oříznut, a to bez ohledu na to, zda jsou v sousedních buňkách volná místa.

Na snímku výše je to patrné u buňky „C3“ – i když jsou v sousedních buňkách „D3“ a dalších volná místa, text je nepodmíněně oříznut.

AutoFitColumn

Hodnota TextOverflowMode.AutoFitColumn řeší problém jinak – zvětší šířku sloupce tak, aby se do ní vešel celý text buňky. Bez ohledu na délku textu v buňce se tedy zvýší šířka sloupce, ve kterém se buňka nachází.

Snímek výše ukazuje, jak to funguje. Samozřejmě může být tento přístup v některých případech nevhodný, zejména pokud jsou buňky s textem extrémně dlouhé – stránka se může stát příliš širokou a vyžadovat nepříjemné horizontální scrollování.

Vykreslovat skryté řádky a sloupce

Microsoft Excel a další tabulkové procesory umožňují skrývat konkrétní řádky a sloupce. Ve výchozím nastavení GroupDocs.Viewer takové řádky a sloupce nevykresluje, ale toto chování lze změnit. Vlastnosti ViewOptions.SpreadsheetOptions.RenderHiddenRows a ViewOptions.SpreadsheetOptions.RenderHiddenColumns při nastavení na true umožňují zobrazit skryté řádky a sloupce ve výstupním souboru při renderování tabulky do HTML, PDF, PNG nebo JPEG.

Vykreslovat skryté listy

Stejně jako skryté řádky a sloupce, může soubor tabulky obsahovat jeden nebo více skrytých listů. Ve výchozím nastavení GroupDocs.Viewer skryté listy nevykresluje. Toto lze změnit pomocí vlastnosti RenderHiddenPages nastavením na true. Je potřeba dodat, že na rozdíl od dříve zmíněných vlastností se RenderHiddenPages nachází ne v SpreadsheetOptions, ale v abstraktní třídě BaseViewOptions, která je společná pro všechny možnosti zobrazení.

Přeskočit prázdné řádky a sloupce

Některé tabulky jsou „řídce vyplněné“ — obsahují mnoho prázdných míst, která zbytečně zabírají místo. GroupDocs.Viewer má funkci, která umožňuje tyto prázdné řádky a sloupce při renderování vynechat. Pokud je tato funkce zapnutá, prázdné řádky a/nebo sloupce jsou z výsledného HTML, PDF, PNG i JPEG vynechány. Za tuto funkci odpovídají booleanové vlastnosti SpreadsheetOptions.SkipEmptyRows a SpreadsheetOptions.SkipEmptyColumns.

Na snímku výše jsou oba přepínače – SkipEmptyRows i SkipEmptyColumns – zapnuté.

Vykreslovat nebo skrývat komentáře buněk

Buňky v tabulkovém dokumentu mohou obsahovat komentáře a ve výchozím nastavení je GroupDocs.Viewer vykresluje všechny. Toto lze zakázat pomocí vlastnosti BaseViewOptions.RemoveComments; pokud je nastavena na true, žádné komentáře nebudou vykresleny. Uveďte, že tato vlastnost se nachází v třídě BaseViewOptions, nikoli v SpreadsheetOptions.

Na snímku výše je ukázáno vykreslení souboru XLSX s komentáři buněk do formátu PNG s výchozími možnostmi – komentář buňky „E2“ je ve výsledném PNG přítomen.

Nastavení okrajů listu na výstupních stránkách PDF

Při renderování listů do PDF lze řídit okraje stránky — vzdálenost v centimetrech od okraje stránky k obsahu. Existují čtyři vlastnosti pro nastavení horního, pravého, dolního a levého okraje:

• SpreadsheetOptions.TopMargin
• SpreadsheetOptions.RightMargin
• SpreadsheetOptions.BottomMargin
• SpreadsheetOptions.LeftMargin

Ve výchozím nastavení mají všechny tyto čtyři vlastnosti záporné hodnoty, což znamená, že jsou použity výchozí okraje definované GroupDocs.Viewer. Lze je však nastavit explicitně. Je nutné zdůraznit, že okraje stránek se aplikují pouze při výstupním formátu PDF.

Následující ukázka kódu demonstruje vytvoření PdfViewOptions, nastavení všech čtyř okrajů a renderování dokumentu:

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);
}

Následující obrázek ukazuje výsledek:

Závěr

Formáty tabulek jsou poměrně složité a dokumenty mohou obsahovat velmi různorodý obsah různého typu a délky. V mnoha případech není možné komplexní tabulkový dokument renderovat do požadovaného formátu s výchozími nastaveními, a proto GroupDocs.Viewer poskytuje tak komplexní sadu vlastností; s jejich pomocí si každý uživatel může renderování přizpůsobit svým potřebám.

Viz také

• Render Excel a Apple Numbers tabulky jako HTML, PDF a soubory obrázků
• Rozdělit list na stránky
• Zadání možností renderování tabulky

Získat bezplatnou zkušební verzi

Bezplatnou zkušební verzi GroupDocs.Viewer pro .NET si můžete stáhnout z releases.groupdocs.com. Dočasnou licenci, která umožňuje vyzkoušet všechny funkce a možnosti bez omezení, získáte zde.