Overzicht

Spreadsheet‑documenten zijn documenten die gegevens bevatten in tabelvorm — in rijen en kolommen. Ze staan ook bekend als de workbooks. Er bestaan veel formaten voor spreadsheet‑documenten — Office Open XML (zoals XLSX, XLSM, enz.), Microsoft Excel Binary File Format (XLS, XLT), OpenDocument Spreadsheet‑formaat (ODS, FODS, OTS), tekstgebaseerde scheidingsteken‑gescheiden formaten (CSV, TSV enz.) en zo verder. Samen vormen ze de zogenoemde Spreadsheet‑formatenfamilie. GroupDocs.Viewer ondersteunt bijna alle spreadsheet‑formaten bij import en maakt het mogelijk ze te renderen (converteren) naar HTML, PDF, PNG en JPEG. Dit artikel legt uit hoe dat kan, welke opties beschikbaar zijn en wanneer en waarom ze gebruikt zouden moeten worden.

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

Basisgebruik

Allereerst moeten we het hebben over opties. Er is een aparte klasse in de publieke API: SpreadsheetOptions in de GroupDocs.Viewer.Options. Deze klasse is speciaal ontworpen om het renderen van de Spreadsheet‑formatenfamilie af te stellen. Hij is toegankelijk voor alle vier weergave‑opties via de SpreadsheetOptions‑eigenschap:

Wanneer deze niet expliciet wordt opgegeven, heeft de eigenschap SpreadsheetOptions een impliciete standaardwaarde van een instantie van de klasse SpreadsheetOptions, hetgeen later in dit artikel wordt toegelicht.

In één oogopslag is het renderen van een Spreadsheet‑document met GroupDocs.Viewer supereenvoudig en vergelijkbaar met alle andere formaten — maak een ViewOptions‑instantie, maak een Viewer‑instantie met het opgegeven invoer‑Spreadsheet‑document, en roep de methode Viewer.View(viewOptions) aan. De volgende code‑voorbeeld toont het renderen van één invoer‑Spreadsheet‑bestand naar alle 4 uitvoerformaten: HTML, PDF, PNG en JPEG. Let op dat, afgezien van het maken van de optieklassen‑instanties, er geen spreadsheet‑specifieke afstemming plaatsvindt; alle spreadsheet‑opties blijven op de standaardwaarden staan.

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

Laten we nu over de werkbladen praten. Elk spreadsheet‑bestand bevat minstens één werkblad. In de meeste tabelverwerkingssoftware, zoals Microsoft Excel, worden werkbladen weergegeven als tabbladen. Sommige spreadsheet‑formaten kunnen slechts één werkblad bevatten; dit geldt bijvoorbeeld voor alle tekstgebaseerde scheidingsteken‑gescheiden formaten (CSV, TSV enz.).

Standaard rendert GroupDocs.Viewer alle werkbladen binnen het opgegeven spreadsheet‑bestand. Maar dit kan worden aangepast. De methode Viewer.View() heeft een overload die een reeks paginanummers ontvangt als tweede parameter — Int32[] pageNumbers. Wanneer deze parameter wordt gebruikt, worden alleen die pagina’s (werkbladen) gerenderd. Deze parameter is universeel en wordt toegepast op alle ondersteunde formaten die pagina’s hebben, maar binnen de Spreadsheet‑formatenfamilie geeft hij exact de werkblad‑nummers aan die moeten worden bekeken.

Let op: paginanummering in het algemeen en werkbladnummering in het bijzonder zijn 1‑gebaseerd, niet 0‑gebaseerd; ze beginnen dus bij “1”, niet bij “0”.

Het voorbeeld hieronder laat zien hoe je het 1e en 3e werkblad rendert naar PNG in een spreadsheet met 3 werkbladen.

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

Werkbladen splitsen in pagina’s

GroupDocs.Viewer rendert documenten naar pagina’s, waarbij onder een pagina we een rechthoekig gebied van relatief kleine afmeting verstaan, vergelijkbaar met het scherm of een A4‑vel. Daarentegen kunnen werkbladen zeer groot zijn. Zo ondersteunt het inmiddels verouderde XLS‑formaat maximaal 256 kolommen en 65 536 rijen, terwijl het nieuwere XLSX (Office Open XML Workbook)‑formaat en Microsoft Excel beide tot 16 384 kolommen en 1 048 576 rijen ondersteunen. “Het passen” van werkbladen op pagina’s is een cruciaal onderdeel van het renderen van spreadsheets met GroupDocs.Viewer. Om een werkblad op pagina(‘s) te laten passen, voert GroupDocs.Viewer een werkblad‑splitsing uit — het werkblad wordt verdeeld in meerdere rechthoekige blokken, en elk blok wordt op een aparte pagina geplaatst. Er zijn 5 verschillende methoden; deze worden hieronder opgesomd en beschreven.

Belangrijk: al deze splitsingsmethoden worden gespecificeerd op dezelfde manier — via een specifieke statische methode (factory‑method) die een instantie van de klasse SpreadsheetOptions maakt.

Het volledige werkblad op één pagina renderen

SpreadsheetOptions.ForOnePagePerSheet()

De makkelijkste en simpelste manier — splitsen uitschakelen en de paginagrootte aanpassen zodat alle inhoud van het volledige werkblad past. Dit is een goede keuze wanneer al bekend is dat het werkblad een kleine omvang heeft. Echter, als een werkblad echt groot is, kan deze aanpak leiden tot slechte resultaten. Vooral bij renderen naar HTML kan het resulterende document enorm worden, tientallen of zelfs honderden MiB, wat problemen oplevert bij weergave in web‑browsers. Bij renderen naar JPEG kunnen de breedte of hoogte de maximale limiet van 65 535 pixels overschrijden. Gebruik deze modus dus bewust.

Render worksheet on one page

Werkblad splitsen op paginabreaks

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel voegt zelf automatische paginabreaks toe op basis van papierformaat en pagina‑instellingen (oriëntatie, marges). Als je naar het tabblad “View” gaat en de modus “Page Break Preview” inschakelt, zie je blauwe lijnen die het hele werkblad opdelen in rechthoekige blokken, elk gelabeld als “Page 1”, “Page 2”, enzovoort. Zo “suggereert” Microsoft Excel een splitsing van werkbladen over pagina’s.

Met deze methode volgt GroupDocs.Viewer Microsoft Excel en splitst de werkbladen volgens de paginabreaks, precies zoals Excel dat doet.

Deze optie — het splitsen van een werkblad op paginabreaks — is de standaardoptie van de eigenschap BaseViewOptions.SpreadsheetOptions; dus wanneer je een instantie van een view‑opties‑klasse maakt, wordt de optie “ForRenderingByPageBreaks()” automatisch geselecteerd.

Alleen het afdrukgebied renderen

SpreadsheetOptions.ForRenderingPrintArea()

Naast paginabreaks kent Microsoft Excel het concept “Print Area”. Een Print Area is één of meer celbereiken in een werkblad die bestemd zijn om afgedrukt te worden; alles buiten de Print Area wordt niet afgedrukt. Om een celbereik toe te voegen aan de Print Area, ga je naar het tabblad “Page Layout”, klik je op de knop “Print Area” en vervolgens op “Set Print Area”. Om een extra bereik toe te voegen, selecteer je het nieuwe bereik, klik je opnieuw op “Print Area” en kies je “Add to Print Area”. In de modus “Page Break Preview” zie je alle celbereiken van de Print Area.

Render only print area

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer heeft een unieke functionaliteit — het combineren van Print Area en paginabreaks in één modus. In dit geval houdt GroupDocs.Viewer zowel alle celbereiken van de Print Area als de paginabreaks in het werkblad in acht en past ze gelijktijdig toe om een werkblad op pagina’s te splitsen.

In de onderstaande screenshot toont de rode lijn de Print Area en de blauwe lijn de paginabreaks.

Render print area and split by page breaks

Werkblad handmatig splitsen op rijen en kolommen

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

Soms is geen van de eerder beschreven splitsingsmethoden acceptabel, of ondersteunt het spreadsheet‑formaat geen paginabreaks en Print Areas, bijvoorbeeld bij tekstgebaseerde CSV. In dat geval laat GroupDocs.Viewer handmatig het aantal rijen en/of kolommen per pagina bepalen. Kortom, het verschil tussen alleen splitsen op rijen versus splitsen op rijen en kolommen wordt geïllustreerd in de screenshot hieronder.

Als de eerste overload van de ForSplitSheetIntoPages‑methode wordt gebruikt (één parameter), wordt alleen splitsen op rijen ingeschakeld. Als de tweede overload wordt aangeroepen (twee parameters), wordt splitsen op rijen en kolommen ingeschakeld.

Split worksheet into pages manually by rows and columns

Aanvullende opties afstemmen

Alles wat hierboven is beschreven, is essentieel en voldoende om spreadsheets te renderen met GroupDocs.Viewer. Er zijn echter tal van extra opties die niet verplicht zijn, maar gebruikers in staat stellen het renderresultaat nog nauwkeuriger af te stemmen.

Sommige van deze opties verschijnen als eigenschappen van de SpreadsheetOptions‑klasse, die zelf toegankelijk is via de SpreadsheetOptions‑eigenschap van de view‑opties‑klasse. Andere bevinden zich in de abstracte klasse ViewOptions, gemeenschappelijk voor alle 4 render‑modi.

Rijen‑ en kolom‑koppen renderen

Wanneer MS Excel of een vergelijkbaar tabelverwerkingsprogramma een spreadsheet‑document opent, toont het de kolom‑ en rij‑koppen; kolommen worden aangeduid met letters (A, B, C, AA, AB, …) en rijen met cijfers (1, 2, 3, …, 1 048 576). Standaard toont GroupDocs.Viewer deze koppen niet, omdat ze onderdeel uitmaken van de gebruikersinterface van de tabelprocessor, niet van het document zelf. Dit kan echter worden gewijzigd met de eigenschap RenderHeadings van type bool. Standaard is hij uitgeschakeld (false), maar wanneer hij op true wordt gezet, verschijnen de rij‑ en kolom‑koppen in het output‑document, zoals in de screenshot hieronder te zien is.

Render row and column headings

Rasterlijnen van het werkblad renderen

Het concept van deze optie is sterk vergelijkbaar met de vorige. Standaard toont GroupDocs.Viewer de rasterlijnen tussen cellen niet, omdat deze geen onderdeel van de spreadsheet zelf zijn, maar een weergave van de tabelprocessor. Met de eigenschap RenderGridLines (bool) kan dit gedrag worden nagebootst. Zet de eigenschap op true en de rasterlijnen zullen verschijnen in het output‑document, zie de screenshot hieronder.

Render worksheet gridlines

Overloop van celtekst gecontroleerd weergeven

Het komt vaak voor dat tekst niet binnen de grenzen van een cel past. Hoe moet deze tekst worden weergegeven? GroupDocs.Viewer biedt de eigenschap SpreadsheetOptions.TextOverflowMode om dit op te lossen. De eigenschap heeft als type de enum TextOverflowMode, met vier mogelijke waarden die hieronder worden uitgelegd.

OverlayIfNextIsEmpty

Standaard heeft SpreadsheetOptions.TextOverflowMode de waarde OverlayIfNextIsEmpty, wat het standaardgedrag van Microsoft Excel imiteert. Deze waarde staat toe dat tekst doorschiet in aangrenzende cellen alleen wanneer die cellen leeg zijn. Zijn ze niet leeg, dan wordt de overlopende tekst afgekapt.

OverlayIfNextIsEmpty enum value

De screenshot toont een HTML‑bestand, gerenderd vanuit een XLSX‑invoer met de waarde OverlayIfNextIsEmpty. Merk op dat cel “B2” een lange tekst heeft die wordt afgekapt omdat “C2” niet leeg is. Cel “C3” heeft daarentegen een lange tekst die wel doorschiet naar “D2” en “E2”, omdat die cellen leeg zijn.

Overlay

De waarde TextOverflowMode.Overlay lijkt op de vorige, maar is agressiever: lange tekst die de originele celgrenzen overschrijdt, schuift altijd door naar aangrenzende cellen, ongeacht of die reeds data bevatten. Eventuele bestaande inhoud in die aangrenzende cellen wordt dan overschreven.

Overlay enum value

In de screenshot ziet men dat de lange tekst uit cel “B2” doorschiet naar “C2”, “D2”, “E2” en “F2”. Daardoor wordt de oorspronkelijke inhoud van “C2” en “F2” gewist.

HideText

De modus TextOverflowMode.HideText werkt precies tegenovergesteld aan Overlay: in plaats van doorschuiven wordt de tekst simpelweg afgekapt zodra deze de celgrenzen overschrijdt, ongeacht of er naast vrije ruimte is.

HideText enum value

In de screenshot is dit te zien bij cel “C3”: hoewel er vrije ruimte is in “D3” en verder, wordt de tekst onvoorwaardelijk afgekapt.

AutoFitColumn

De waarde TextOverflowMode.AutoFitColumn lost het probleem op een andere manier — de kolombreedte wordt automatisch vergroot zodat de tekst in elke cel past. Ongeacht hoe lang de tekst in een bepaalde cel is, wordt de breedte van de kolom (of kolommen) waarin die cel zich bevindt aangepast zodat de volledige tekenreeks past.

AutoFitColumn enum value

De screenshot toont dit gedrag. Let op: dit kan in sommige situaties onpraktisch zijn, vooral bij extreem lange teksten, omdat het de pagina extreem breed maakt en horisontale scrollbalken veroorzaakt.

Verborgen rijen en kolommen renderen

Microsoft Excel en andere tabelprocessoren laten toe rijen en kolommen te verbergen. Standaard rendert GroupDocs.Viewer deze verborgen rijen/kolommen niet, maar dit gedrag kan worden gewijzigd. Zet de eigenschappen ViewOptions.SpreadsheetOptions.RenderHiddenRows en ViewOptions.SpreadsheetOptions.RenderHiddenColumns op true om verborgen rijen en kolommen zichtbaar te maken in de output‑file bij renderen naar HTML, PDF, PNG of JPEG.

Verborgen werkbladen renderen

Net als bij verborgen rijen/kolommen kan een spreadsheet‑bestand één of meer verborgen werkbladen bevatten. Standaard rendert GroupDocs.Viewer deze niet, maar dit kan worden aangepast via de eigenschap RenderHiddenPages door deze op true te zetten. Let op: in tegenstelling tot de eerder genoemde eigenschappen bevindt RenderHiddenPages zich niet in SpreadsheetOptions, maar in de abstracte klasse BaseViewOptions, die gemeenschappelijk is voor alle view‑opties.

Lege rijen en kolommen overslaan

Sommige spreadsheets zijn “sparse” — ze bevatten veel lege cellen die onnodig ruimte innemen. GroupDocs.Viewer biedt een functie om lege rijen en kolommen over te slaan tijdens het renderen. Wanneer deze functie actief is, worden lege rijen en/of kolommen weggelaten uit het resulterende HTML, PDF, PNG en JPEG. De bool‑eigenschappen SpreadsheetOptions.SkipEmptyRows en SpreadsheetOptions.SkipEmptyColumns regelen dit.

Skip empty rows and columns

De screenshot toont dat zowel SkipEmptyRows als SkipEmptyColumns zijn ingeschakeld.

Celcommentaren renderen of verbergen

Cellen in een spreadsheet‑document kunnen commentaren bevatten, en standaard rendert GroupDocs.Viewer ze allemaal. Dit kan worden uitgeschakeld via de eigenschap BaseViewOptions.RemoveComments; zet je deze op true, dan worden er geen commentaren getoond. Deze eigenschap bevindt zich in de klasse BaseViewOptions, niet in SpreadsheetOptions.

Render or hide cell comments

De screenshot toont een gerenderde XLSX‑file met celcommentaar naar PNG met de standaardopties — het commentaar bij cel “E2” is aanwezig in de PNG‑output.

Werkbladmarges instellen in de PDF‑output

Bij het renderen van werkbladen naar PDF is het mogelijk de paginamarges te regelen — de afstand in centimeters tussen de paginakant en de inhoud. Er zijn vier eigenschappen om de boven‑, rechter‑, onder‑ en linkermarge te bepalen:

Standaard hebben al deze vier eigenschappen negatieve waarden, wat betekent dat de standaardmarges van GroupDocs.Viewer worden toegepast. Het is echter mogelijk de waarden expliciet in te stellen. Merk op dat paginamarges alleen van toepassing zijn wanneer het doelformaat PDF is.

De onderstaande code laat zien hoe je een PdfViewOptions maakt, alle vier marges instelt en een document rendert:

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

Het volgende beeld toont het resultaat:

Set worksheet margins in the output PDF pages

Conclusie

Spreadsheet‑formaten zijn behoorlijk complex, en documenten kunnen sterk uiteenlopende inhoud van verschillende typen en lengtes bevatten. In veel gevallen is het onmogelijk een complex spreadsheet‑document te renderen naar een bepaald formaat met alleen de standaardinstellingen; daarom biedt GroupDocs.Viewer een uitgebreid pakket aan eigenschappen waarmee elke gebruiker het renderen kan afstemmen op zijn eigen behoeften.

Zie ook

Gratis proefversie

Je kunt een gratis proefversie van GroupDocs.Viewer voor .NET downloaden via releases.groupdocs.com. Je kunt ook een tijdelijke licentie verkrijgen om alle functies en mogelijkheden onbeperkt uit te proberen via hier.