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é oddělovači (CSV, TSV atd.) a tak dále. Všechny patří do takzvané rodiny formátů Spreadsheet. GroupDocs.Viewer podporuje téměř všechny formáty tabulek při importu a umožňuje je renderovat (převádět) 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č by se měly použít.

Rendering a workbook, opened in MS Excel, to the HTML format

Základní použití

Nejprve musíme mluvit o možnostech. Ve veřejném API existuje samostatná třída: SpreadsheetOptions v prostoru názvů GroupDocs.Viewer.Options. Tato třída je navržena speciálně pro nastavení renderování rodiny formátů Spreadsheet. Je přístupná pro všechny čtyři možnosti zobrazení prostřednictvím vlastnosti SpreadsheetOptions :

Pokud není explicitně zadáno, má vlastnost SpreadsheetOptions výchozí implicitní hodnotu instance třídy SpreadsheetOptions, která bude v tomto článku podrobněji vysvětlena.

Na první pohled je renderování tabulkového dokumentu pomocí GroupDocs.Viewer naprosto jednoduché a podobné všem ostatním formátům – vytvoříte instanci ViewOptions, vytvoříte instanci Viewer s určeným vstupním tabulkovým dokumentem a zavoláte metodu Viewer.View(viewOptions). Následující ukázka kódu demonstruje renderování jediného vstupního souboru Spreadsheet do všech 4 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é ladění specifické pro tabulky, takže všechny možnosti spreadsheet jsou nastaveny na 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í si povíme o listách (worksheets). Každý spreadsheet má alespoň jednu list. Ve většině tabulkových programů, jako je Microsoft Excel, jsou listy reprezentovány jako záložky. Některé formáty mohou mít jen jediný list; to zahrnuje například všechny textové formáty oddělené oddělovači (CSV, TSV atd.).

Ve výchozím nastavení GroupDocs.Viewer renderuje všechny listy v daném spreadsheetu. Toto lze změnit. Metoda Viewer.View() má přetížení, které přijímá sadu čísel stránek jako druhý parametr – Int32[] pageNumbers. Když je tento parametr použit, budou renderovány jen tyto stránky. Tento parametr je univerzální a platí pro všechny podporované formáty, které mají stránky, ale v kontextu rodiny formátů Spreadsheet popisuje právě čísla listů, které se mají zobrazit.

Všimněte si, že číslování stránek obecně a číslování listů konkrétně je 1‑základní, ne 0‑základní, takže začíná od „1“, ne od „0“.

Níže uvedený příklad ukazuje, jak renderovat 1. a 3. list do PNG v spreadsheetu, 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 renderuje dokumenty na stránky, kde pod stránkou rozumíme nějakou obdélníkovou oblast relativně malé velikosti, srovnatelnou s oblastí displeje nebo papíru formátu A4. Na druhou stranu mohou být listy velmi velké. Konkrétně nyní již zastaralý formát XLS podporuje max 256 sloupců a 65536 řádků, zatímco novější formát XLSX (Office Open XML Workbook) a Microsoft Excel oba podporují až 16384 sloupců a 1048576 řádků. „Vložení“ listů do stránek je klíčovou součástí renderování tabulek pomocí GroupDocs.Viewer. Aby se list vešel na stránku(y), GroupDocs.Viewer provádí rozdělení listu – list je rozdělen na více obdélníkových částí a každá z nich je umístěna na samostatnou stránku. Existuje 5 různých metod, které jsou uvedeny a popsány níže.

Co je důležité – všechny tyto metody rozdělení jsou specifikovány stejným způsobem – pomocí konkrétní statické metody (factory method), která vytvoří instanci třídy SpreadsheetOptions.

Renderovat celý list na jedné stránce

SpreadsheetOptions.ForOnePagePerSheet()

Nejjednodušší a nejpřímější způsob – vypnout rozdělení a upravit velikost stránky tak, aby se vešel celý obsah listu. Toto je dobrá volba, pokud už víte, že list má malou velikost. Pokud je však list opravdu velký, může tento přístup vést k špatným výsledkům. Konkrétně při renderování do HTML může být výsledný HTML dokument obrovský, desítky nebo i stovky MiB, což může způsobit problémy při prohlížení takových souborů v prohlížečích. Při renderování do JPEG může být situace ještě horší, pokud šířka nebo výška překročí maximální limit 65535 pixelů. Používejte tento režim tedy uvážlivě.

Render worksheet on one page

Rozdělit list podle zalomení stránky

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel sám přidává automatické zalomení stránky na základě velikosti papíru a nastavení stránky, jako je orientace a okraje. Pokud přejdete na kartu „View“ a vstoupíte do režimu „Page Break Preview“, uvidíte modré čáry, které dělí celý list na obdélníkové úseky, z nichž každý je označen jako „Page 1“, „Page 2“ atd. Takto Microsoft Excel „navrhuje“ rozdělení listu na stránky.

Touto metodou GroupDocs.Viewer následuje Microsoft Excel a rozděluje listy podle zalomení stránky, stejně jako to dělá Excel.

Je třeba zmínit, že tato volba – rozdělit list podle zalomení stránky – je výchozí volbou vlastnosti BaseViewOptions.SpreadsheetOptions, takže když vytvoříte instanci třídy možností zobrazení, je výchozí volbou [ForRenderingByPageBreaks()].

Renderovat pouze tiskovou oblast

SpreadsheetOptions.ForRenderingPrintArea()

Kromě zalomení stránky má Microsoft Excel koncept „Print Area“. Tisková oblast je ve skutečnosti jeden nebo více rozsahů buněk v listu, které jsou určeny k tisku; jakýkoli obsah mimo tiskovou oblast se vůbec netiskne. Pro přidání nějakého rozsahu buněk do tiskové oblasti přejděte na kartu „Page Layout“, klikněte na tlačítko „Print Area“ a poté na položku „Set Print Area“ (viz snímek níže). Pro přidání dalšího rozsahu do tiskové oblasti vyberte nový rozsah, klikněte na tlačítko „Print Area“ a poté na položku „Add to Print Area“. V režimu „Page Break Preview“ můžete vidět všechny rozsahy buněk v tiskové oblasti.

Render only print area

Renderovat tiskovou oblast a rozdělit podle zalomení stránky

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer má jedinečnou funkci – kombinaci tiskové oblasti a zalomení stránky v jednom režimu. V tomto případě GroupDocs.Viewer bere v úvahu všechny rozsahy buněk tiskové oblasti i zalomení stránky v listu a aplikuje je současně k rozdělení listu na stránky.

Na následujícím snímku červená čára ukazuje tiskovou oblast a modrá čára ukazuje zalomení stránky.

Render print area and split by page breaks

Rozdělit list na stránky ručně 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 spreadsheet má formát, který nepodporuje zalomení stránky a tiskové oblasti, například textový CSV. Pro takové případy GroupDocs.Viewer umožňuje ručně zadat počet řádků a/nebo počet sloupců, které mají být na každé stránce. Stručně řečeno, rozdíl mezi rozdělením jen podle řádků a rozdělením podle řádků a sloupců je znázorněn na snímku níže.

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

Split worksheet into pages manually by rows and columns

Úprava dalších možností

Vše výše popsané je podstatné a stačí pro renderování spreadsheetů pomocí GroupDocs.Viewer. Existuje však řada dalších možností, které nejsou povinné, ale umožňují uživatelům ještě lépe přizpůsobit výsledek renderování.

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

Renderovat záhlaví řádků a sloupců

Když MS Excel nebo podobný program pro zpracování tabulek otevře spreadsheet, zobrazí 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í tato záhlaví nezobrazuje, protože jsou součástí rozhraní tabulkového procesoru, nikoli samotného dokumentu. Toto lze změnit pomocí vlastnosti RenderHeadings typu boolean. Ve výchozím nastavení je zakázána a má hodnotu false, ale když je povolena (true), budou v výstupním dokumentu přítomna záhlaví řádků a sloupců, jak je vidět na snímku níže.

Render row and column headings

Renderovat mřížku listu

Koncept této možnosti je velmi podobný předchozímu. Ve výchozím nastavení GroupDocs.Viewer nezobrazuje mřížku mezi buňkami, protože není součástí spreadsheetu, ale spíše způsobem, jakým tabulkový procesor reprezentuje obsah tabulky. Pomocí vlastnosti RenderGridLines typu boolean je však možné napodobit chování MS Excel. Nastavte hodnotu true pro vlastnost SpreadsheetOptions.RenderGridLines a mřížka bude v výstupním dokumentu přítomna, jak ukazuje snímek níže.

Render worksheet gridlines

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

Jedná se o poměrně častý scénář, kdy text v buňce nepřesahuje její hranice. Jak tento text správně zobrazit? GroupDocs.Viewer poskytuje speciální vlastnost SpreadsheetOptions.TextOverflowMode pro řešení takového problému. Vlastnost TextOverflowMode má typ se stejným názvem, TextOverflowMode, a jedná se o výčtový typ se 4 možnými položkami, které jsou vysvětleny níže.

OverlayIfNextIsEmpty

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

OverlayIfNextIsEmpty enum value

Na snímku výše je zobrazen HTML soubor renderovaný ze vstupního XLSX s hodnotou OverlayIfNextIsEmpty. Všimněte si buňky „B2“ – má dlouhý text, který je oříznut, protože buňka „C2“ není prázdná. Buňka „C3“ má také dlouhý text, který se nevejde, ale přeteče do buněk „D2“ a „E2“, protože jsou prázdné.

Overlay

Hodnota TextOverflowMode.Overlay je mírně podobná předchozí, ale lze ji považovat za agresivnější: dlouhý text, který se nevejde do původních hranic buňky, vždy přeteče, bez ohledu na sousední buňky. Pokud sousední buňky také obsahují nějaký text nebo jiná data, budou přepsána.

Overlay enum value

Snímek výše ukazuje, jak to funguje. Dlouhý text z buňky „B2“ přeteče do sousedních buněk „C2“, „D2“, „E2“, „F2“. Výsledkem je, že původní text v buňkách „C2“ a „F2“ je smazán.

HideText

Režim TextOverflowMode.HideText funguje opačně k předchozímu režimu Overlay – místo přetečení text nakonec ořízne, pokud se nevejde do hranic vlastní buňky, bez ohledu na to, zda je v sousedních buňkách volný prostor.

HideText enum value

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

AutoFitColumn

Hodnota TextOverflowMode.AutoFitColumn řeší problém jiným přístupem – zvětší šířku sloupce tak, aby se vešel text jakékoli buňky. Takže bez ohledu na to, jak dlouhý text v konkrétní buňce je, šířka sloupců, ve kterých se buňka nachází, bude zvýšena tak, aby pojmula celý řetězec.

AutoFitColumn enum value

Snímek výše ukazuje, jak to funguje. Samozřejmě tento přístup nemusí být vhodný v některých případech, zejména když je text v buňkách extrémně dlouhý – stránka se může stát velmi širokou a způsobit nepříjemné horizontální posouvání.

Renderovat skryté řádky a sloupce

Microsoft Excel a další tabulkové procesory umožňují skrýt konkrétní řádky a sloupce. Ve výchozím nastavení GroupDocs.Viewer takové řádky a sloupce nerenderuje, 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í spreadsheetu do HTML, PDF, PNG nebo JPEG.

Renderovat skryté listy

Stejně jako skryté řádky a sloupce, může soubor spreadsheet obsahovat jeden nebo více skrytých listů. A stejně jako v předchozím případě, ve výchozím nastavení GroupDocs.Viewer skryté listy nerenderuje. Toto lze změnit pomocí vlastnosti RenderHiddenPages nastavením její hodnoty na true. Je třeba zmínit, že na rozdíl od dříve popsaných vlastností se RenderHiddenPages nachází ne v SpreadsheetOptions, ale v abstraktní třídě BaseViewOptions, společné pro všechny možnosti zobrazení.

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

Některé spreadsheety jsou „řídce vyplněné“ – obsahují mnoho prázdných míst, která mohou zabírat příliš mnoho místa. GroupDocs.Viewer má funkci, která umožňuje přeskočit prázdné řádky a sloupce při renderování. Pokud je tato funkce povolena, prázdné řádky a/nebo sloupce jsou vyloučeny z výsledného HTML, PDF, PNG a JPEG. Za tuto funkci odpovídají booleanové vlastnosti SpreadsheetOptions.SkipEmptyRows a SpreadsheetOptions.SkipEmptyColumns.

Skip empty rows and columns

Snímek výše ukazuje, že jsou povoleny jak SkipEmptyRows, tak SkipEmptyColumns.

Renderovat nebo skrýt komentáře buněk

Buňky v spreadsheetu mohou mít komentáře a ve výchozím nastavení je GroupDocs.Viewer všechny renderuje. Toto lze zakázat pomocí vlastnosti BaseViewOptions.RemoveComments – pokud nastavíte její hodnotu na true, nebudou žádné komentáře renderovány. Všimněte si, že tato vlastnost se nachází ve třídě BaseViewOptions, nikoli v SpreadsheetOptions.

Render or hide cell comments

Snímek výše ukazuje renderování souboru XLSX s komentáři buněk do formátu PNG s výchozími možnostmi – komentář pro buňku „E2“ je ve výsledném PNG souboru přítomen.

Nastavit okraje listu ve výstupních PDF stránkách

Při renderování listů do formátu PDF je možné řídit okraje stránky – vzdálenost v centimetrech od okraje stránky k obsahu. Existují 4 vlastnosti pro řízení horního, pravého, dolního a levého okraje:

Ve výchozím nastavení mají všechny tyto 4 vlastnosti záporné hodnoty, což znamená, že výchozí okraje jsou aplikovány GroupDocs.Viewer. Je však možné tyto hodnoty nastavit explicitně. Je třeba zdůraznit, že okraje stránky se aplikují pouze tehdy, když je cílový formát PDF.

Následující úryvek kódu ukazuje vytvoření PdfViewOptions, nastavení všech 4 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:

Set worksheet margins in the output PDF pages

Závěr

Formáty spreadsheet jsou poměrně složité a dokumenty mohou mít velmi různorodý obsah různého typu a délky. V mnoha případech je nemožné renderovat komplexní spreadsheet dokument do nějakého formátu s výchozími možnostmi, a proto GroupDocs.Viewer poskytuje tak komplexní sadu vlastností; s nimi bude každý uživatel schopen přizpůsobit renderování svým potřebám.

Viz také

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á vám umožní vyzkoušet všechny funkce a možnosti bez omezení, můžete získat zde.