Überblick
Tabellendokumente sind Dokumente, die Daten in Tabellenform — in Zeilen und Spalten — enthalten. Sie sind auch als Arbeitsmappen bekannt. Es gibt viele Formate von Tabellendokumenten — Office Open XML (wie XLSX, XLSM usw.), Microsoft Excel Binary File Format (XLS, XLT), OpenDocument Spreadsheet‑Format (ODS, FODS, OTS), textbasierte, durch Trennzeichen getrennte Formate (CSV, TSV usw.) und so weiter. All diese bilden die sogenannte Spreadsheet‑Formate‑Familie. GroupDocs.Viewer unterstützt fast alle Spreadsheet‑Formate beim Import und ermöglicht deren Rendering (Konvertierung) nach HTML, PDF, PNG und JPEG. Dieser Artikel erklärt, wie das funktioniert, welche Optionen zur Verfügung stehen und wann und warum sie eingesetzt werden sollten.
Grundlegende Verwendung
Zunächst müssen wir über Optionen sprechen. Es gibt eine eigene Klasse in der öffentlichen API: SpreadsheetOptions im Namespace GroupDocs.Viewer.Options. Diese Klasse ist speziell dafür vorgesehen, das Rendering der Spreadsheet‑Formate‑Familie anzupassen. Sie ist über die Eigenschaft SpreadsheetOptions in allen vier View‑Optionen zugänglich:
- HtmlViewOptions.SpreadsheetOptions beim Rendern eines Spreadsheet‑Dokuments nach HTML,
- PdfViewOptions.SpreadsheetOptions beim Rendern eines Spreadsheet‑Dokuments nach PDF,
- PngViewOptions.SpreadsheetOptions beim Rendern eines Spreadsheet‑Dokuments nach PNG,
- JpgViewOptions.SpreadsheetOptions beim Rendern eines Spreadsheet‑Dokuments nach JPEG.
Wird diese Eigenschaft nicht explizit angegeben, hat SpreadsheetOptions implizit den Standardwert einer Instanz der Klasse SpreadsheetOptions, wie später in diesem Artikel erläutert wird.
Kurz gesagt: Das Rendern eines Spreadsheet‑Dokuments mit GroupDocs.Viewer ist super‑einfach und funktioniert genauso wie bei allen anderen Formaten — eine Instanz von ViewOptions erzeugen, eine Instanz von Viewer mit dem zu rendernden Spreadsheet‑Dokument erstellen und die Methode Viewer.View(viewOptions) aufrufen. Das folgende Code‑Beispiel zeigt das Rendering einer einzelnen Eingabe‑Spreadsheet‑Datei in alle vier Ausgabeformate: HTML, PDF, PNG und JPEG. Beachten Sie, dass außer dem Erzeugen der Options‑Klassen keine Spreadsheet‑spezifischen Anpassungen vorgenommen wurden, sodass alle Optionen ihre Standardwerte behalten.
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);
}
Nun zu den Arbeitsblättern. Jedes Spreadsheet besitzt mindestens ein Arbeitsblatt. In den meisten Tabellenkalkulationsprogrammen wie Microsoft Excel werden die Arbeitsblätter als Tabs dargestellt. Manche Spreadsheet‑Formate haben nur ein einziges Arbeitsblatt; dazu zählen beispielsweise alle textbasierten, durch Trennzeichen getrennten Formate (CSV, TSV usw.).
Standardmäßig rendert GroupDocs.Viewer alle Arbeitsblätter der angegebenen Arbeitsmappe. Das lässt sich jedoch ändern. Die Methode Viewer.View() verfügt über eine Überladung, die als zweiten Parameter ein Array von Seitenzahlen (Int32[] pageNumbers) annimmt. Wird dieser Parameter verwendet, werden nur die angegebenen Seiten gerendert. Dieser Parameter ist universell und gilt für alle unterstützten Formate, die Seiten besitzen; im Kontext der Spreadsheet‑Formate‑Familie beschreibt er jedoch genau die zu rendernden Arbeitsblatt‑Nummern.
Bitte beachten Sie, dass die Nummerierung von Seiten bzw. Arbeitsblättern eins‑basiert ist, also bei „1“ beginnt und nicht bei „0“.
Das folgende Beispiel zeigt, wie das 1. und 3. Arbeitsblatt einer Arbeitsmappe mit drei Arbeitsblättern nach PNG gerendert wird.
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);
}
Arbeitsblätter in Seiten aufteilen
GroupDocs.Viewer rendert Dokumente seitenweise, wobei unter einer Seite ein rechteckiger Bereich von relativ kleiner Größe verstanden wird – vergleichbar mit dem Anzeigebereich eines Bildschirms oder einer A4‑Seite. Andererseits können Arbeitsblätter sehr groß sein. Das inzwischen veraltete XLS-Format unterstützt maximal 256 Spalten und 65 536 Zeilen ¹, während das neuere XLSX (Office Open XML Workbook) und Microsoft Excel bis zu 16 384 Spalten und 1 048 576 Zeilen unterstützen ². Das „Einpassen“ von Arbeitsblättern in Seiten ist ein entscheidender Schritt beim Rendering von Spreadsheets mit GroupDocs.Viewer. Um ein Arbeitsblatt in eine oder mehrere Seiten zu passen, führt GroupDocs.Viewer eine Arbeitsblatt‑Aufteilung durch – das Arbeitsblatt wird in mehrere rechteckige Stücke zerlegt, die jeweils auf einer eigenen Seite dargestellt werden. Es gibt fünf verschiedene Methoden, die im Folgenden aufgelistet und beschrieben werden.
Wichtig: Alle diese Aufteilungsmethoden werden auf dieselbe Weise angegeben – über eine spezifische statische (Factory‑)Methode, die eine Instanz der Klasse SpreadsheetOptions erzeugt.
Ganzes Arbeitsblatt auf einer Seite rendern
SpreadsheetOptions.ForOnePagePerSheet()
Der einfachste Ansatz – die Aufteilung ausschalten und die Seitengröße so anpassen, dass der gesamte Inhalt des Arbeitsblatts auf eine Seite passt. Dies ist eine gute Wahl, wenn bereits bekannt ist, dass das Arbeitsblatt klein ist. Bei sehr großen Arbeitsblättern kann dieser Ansatz jedoch zu unpraktikablen Ergebnissen führen. Insbesondere beim Rendern nach HTML kann das resultierende Dokument riesig werden – mehrere zehn oder sogar hundert MiB ³ –, was das Anzeigen in Web‑Browsern erschwert. Beim Rendern nach JPEG können Breite oder Höhe die maximale Grenze von 65 535 Pixel überschreiten. Nutzen Sie diesen Modus also bewusst.
Arbeitsblatt anhand von Seitenumbrüchen aufteilen
SpreadsheetOptions.ForRenderingByPageBreaks()
Microsoft Excel fügt automatisch Seitenumbrüche basierend auf Papiergröße und Seiteneinstellungen (Ausrichtung, Ränder) ein. Wechseln Sie zur Registerkarte „Ansicht“ und wählen Sie „Seitenumbruch‑Vorschau“; Sie sehen blaue Linien, die das Arbeitsblatt in rechteckige Abschnitte unterteilen, die mit „Seite 1“, „Seite 2“ usw. beschriftet sind. So „schlägt“ Microsoft Excel vor, das Arbeitsblatt zu teilen.
Mit dieser Methode folgt GroupDocs.Viewer dem Vorgehen von Microsoft Excel und teilt die Arbeitsblätter entsprechend den Seitenumbrüchen.
Hinweis: Diese Option – das Aufteilen nach Seitenumbrüchen – ist die Standardoption der Eigenschaft BaseViewOptions.SpreadsheetOptions. Beim Erzeugen einer View‑Options‑Instanz ist daher ForRenderingByPageBreaks() bereits voreingestellt.
Nur den Druckbereich rendern
SpreadsheetOptions.ForRenderingPrintArea()
Zusätzlich zu den Seitenumbrüchen kennt Microsoft Excel das Konzept des Druckbereichs. Der Druckbereich umfasst ein oder mehrere Zellbereiche, die zum Drucken vorgesehen sind; alles außerhalb wird nicht gedruckt. Einen Zellbereich zum Druckbereich hinzufügen Sie über die Registerkarte „Seitenlayout“, den Button „Druckbereich“ und dann „Druckbereich festlegen“ (siehe Screenshot). Um einen weiteren Bereich hinzuzufügen, zuerst den neuen Bereich auswählen, dann wieder „Druckbereich“ → „Zum Druckbereich hinzufügen“ klicken. In der „Seitenumbruch‑Vorschau“ werden alle Druckbereichs‑Zellbereiche angezeigt.
Druckbereich rendern und nach Seitenumbrüchen aufteilen
SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()
GroupDocs.Viewer bietet ein Alleinstellungsmerkmal – die Kombination aus Druckbereich und Seitenumbrüchen in einem Modus. Dabei werden sowohl alle Zellen des Druckbereichs als auch die Seitenumbrüche berücksichtigt und simultan verwendet, um das Arbeitsblatt in Seiten zu teilen.
Im folgenden Screenshot ist die rote Linie der Druckbereich, die blaue Linie die Seitenumbrüche.
Arbeitsblatt manuell nach Zeilen und Spalten in Seiten aufteilen
SpreadsheetOptions.ForSplitSheetIntoPages(int countRowsPerPage)
SpreadsheetOptions.ForSplitSheetIntoPages(int countRowsPerPage, int countColumnsPerPage)
Manchmal ist keine der oben beschriebenen Aufteilungsmethoden akzeptabel, oder das Spreadsheet‑Format unterstützt weder Seitenumbrüche noch Druckbereiche – beispielsweise bei textbasierten CSV‑Dateien. Für solche Fälle erlaubt GroupDocs.Viewer, die Anzahl der Zeilen und/oder Spalten pro Seite manuell festzulegen. Kurz gesagt: Der Unterschied zwischen „Nur nach Zeilen teilen“ und „Nach Zeilen + Spalten teilen“ wird im folgenden Screenshot verdeutlicht.
Wenn die 1. Überladung von ForSplitSheetIntoPages (ein Parameter) verwendet wird, ist das Teilen nur nach Zeilen aktiviert. Wird die 2. Überladung (zwei Parameter) verwendet, wird nach Zeilen und Spalten geteilt.
Weitere Optionen anpassen
All das oben Beschriebene ist grundlegend und reicht aus, um Spreadsheets mit GroupDocs.Viewer zu rendern. Dennoch gibt es zahlreiche zusätzliche Optionen, die nicht zwingend erforderlich, aber sehr nützlich sind, um das Rendering‑Ergebnis weiter zu verfeinern.
Einige dieser Optionen sind Eigenschaften der Klasse SpreadsheetOptions, die über die Eigenschaft SpreadsheetOptions der View‑Option‑Klassen zugänglich ist. Andere befinden sich in der abstrakten Klasse ViewOptions, die allen vier Rendering‑Modi gemeinsam ist.
Zeilen‑ und Spalten‑Kopfzeilen rendern
Wenn MS Excel oder ein ähnliches Tabellenprogramm ein Spreadsheet‑Dokument öffnet, zeigt es Zeilen‑ und Spalten‑Kopfzeilen an: Spalten werden alphabetisch (A, B, C, AA, AB …) und Zeilen numerisch (1, 2, 3 …, 1048576) bezeichnet. Beim Rendern lässt GroupDocs.Viewer diese Kopfzeilen standardmäßig weg, da sie Teil der Benutzeroberfläche des Tabellenprogramms, nicht des Dokuments selbst, sind. Mit der booleschen Eigenschaft RenderHeadings kann dieses Verhalten umgekehrt werden. Standardwert ist false; bei true werden Zeilen‑ und Spalten‑Kopfzeilen im Ausgabedokument angezeigt – siehe Screenshot unten.
Rasterlinien des Arbeitsblatts rendern
Dieses Feature ist dem vorherigen sehr ähnlich. Standardmäßig zeigt GroupDocs.Viewer keine Rasterlinien zwischen den Zellen, da sie nicht zum eigentlichen Spreadsheet‑Inhalt gehören, sondern lediglich die Darstellung im Tabellenprogramm unterstützen. Durch Setzen der booleschen Eigenschaft RenderGridLines auf true können die Rasterlinien angezeigt werden, wie im nachfolgenden Screenshot demonstriert.
Überlauf von Zelltext steuern
Ein häufiges Szenario: Der Text einer Zelle ist zu lang und passt nicht in die Zellgrenzen. Wie soll dieser Text dargestellt werden? GroupDocs.Viewer bietet die Eigenschaft SpreadsheetOptions.TextOverflowMode zur Lösung dieses Problems. TextOverflowMode ist ein Enum mit vier möglichen Werten, die nachfolgend erläutert werden.
OverlayIfNextIsEmpty
Standardwert von SpreadsheetOptions.TextOverflowMode ist OverlayIfNextIsEmpty. Dieses Verhalten entspricht dem Standard von Microsoft Excel: Text darf in benachbarte Zellen überlaufen, jedoch nur, wenn diese leer sind. Sind benachbarte Zellen belegt, wird der überlaufende Text abgeschnitten.
Im Screenshot sehen Sie die gerenderte HTML‑Datei, erzeugt aus einer XLSX‑Datei mit dem Wert OverlayIfNextIsEmpty. Die Zelle B2 enthält langen Text, wird aber abgeschnitten, weil C2 nicht leer ist. Die Zelle C3 enthält ebenfalls langen Text, der jedoch nach D2 und E2 überläuft, weil diese leer sind.
Overlay
Der Wert Overlay ist dem vorherigen ähnlich, agiert jedoch aggressiver: Langer Text, der nicht in die ursprüngliche Zelle passt, überschreibt immer benachbarte Zellen, unabhängig davon, ob dort bereits Daten stehen.
Im Screenshot fließt der lange Text aus B2 in die Zellen C2, D2, E2, F2 über; dadurch werden die ursprünglichen Inhalte von C2 und F2 gelöscht.
HideText
TextOverflowMode.HideText bewirkt das Gegenstück zu Overlay: Der Text wird stets abgeschnitten, sobald er nicht mehr in die eigene Zelle passt – egal, ob benachbarte Zellen frei sind oder nicht.
Im Screenshot ist dies an Zelle C3 zu erkennen: Trotz freiem Platz in D3 und weiter wird der Text unverzüglich gekürzt.
AutoFitColumn
Der Wert AutoFitColumn löst das Problem, indem die Spaltenbreite so weit vergrößert wird, dass der Text vollständig hineinpasst. Unabhängig von der Textlänge wird die Breite der betreffenden Spalten angepasst.
Der Screenshot zeigt die Funktionsweise. Hinweis: Diese Methode kann zu extrem breiten Seiten führen, die horizontales Scrollen notwendig machen – besonders bei sehr langen Texten.
Versteckte Zeilen und Spalten rendern
Microsoft Excel und andere Tabellenprogramme erlauben das Ausblenden bestimmter Zeilen bzw. Spalten. Standardmäßig rendert GroupDocs.Viewer solche Zeilen/Spalten nicht. Durch Setzen der Eigenschaften ViewOptions.SpreadsheetOptions.RenderHiddenRows und ViewOptions.SpreadsheetOptions.RenderHiddenColumns auf true können ausgeblendete Zeilen bzw. Spalten im Ausgabedokument angezeigt werden (HTML, PDF, PNG oder JPEG).
Versteckte Arbeitsblätter rendern
Analog zu versteckten Zeilen/Spalten kann ein Spreadsheet‑Dokument ein oder mehrere versteckte Arbeitsblätter enthalten. Standardmäßig werden diese nicht gerendert. Durch Setzen der Eigenschaft RenderHiddenPages auf true können versteckte Arbeitsblätter angezeigt werden. Beachten Sie, dass sich RenderHiddenPages nicht in SpreadsheetOptions, sondern in der abstrakten Klasse BaseViewOptions befindet, die allen View‑Optionen gemeinsam ist.
Leere Zeilen und Spalten überspringen
Manche Spreadsheets sind „spärlich“ und enthalten viele leere Zeilen bzw. Spalten, die unnötig Platz beanspruchen. GroupDocs.Viewer kann diese beim Rendern weglassen. Die booleschen Eigenschaften SpreadsheetOptions.SkipEmptyRows und SpreadsheetOptions.SkipEmptyColumns steuern dieses Verhalten.
Der Screenshot zeigt, dass sowohl SkipEmptyRows als auch SkipEmptyColumns aktiviert sind.
Zellkommentare rendern oder ausblenden
Zellen können Kommentare enthalten; standardmäßig rendert GroupDocs.Viewer diese. Durch Setzen der Eigenschaft BaseViewOptions.RemoveComments auf true werden keinerlei Kommentare gerendert. Diese Eigenschaft befindet sich in der Klasse BaseViewOptions, nicht in SpreadsheetOptions.
Der Screenshot demonstriert das Rendern einer XLSX‑Datei mit Zellkommentaren nach PNG – der Kommentar in Zelle E2 ist im Ergebnis sichtbar.
Seitenränder des Arbeitsblatts in PDF‑Ausgabeseiten festlegen
Beim Rendern von Arbeitsblättern nach PDF können die Seitenränder (Abstand in Zentimetern vom Seitenrand zum Inhalt) gesteuert werden. Es gibt vier Eigenschaften für oberen, rechten, unteren und linken Rand:
SpreadsheetOptions.TopMarginSpreadsheetOptions.RightMarginSpreadsheetOptions.BottomMarginSpreadsheetOptions.LeftMargin
Standardmäßig haben diese vier Eigenschaften negative Werte, wodurch die Standard‑Ränder von GroupDocs.Viewer verwendet werden. Sie können jedoch explizit gesetzt werden. Hinweis: Seitenränder gelten nur, wenn das Ziel‑Format PDF ist.
Der folgende Code illustriert das Erzeugen von PdfViewOptions, das Setzen aller vier Ränder und das Rendern eines Dokuments:
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);
}
Das folgende Bild zeigt das Ergebnis:
Fazit
Spreadsheet‑Formate sind äußerst komplex, und Dokumente können sehr unterschiedliche Inhalte unterschiedlicher Größe und Art aufweisen. In vielen Fällen reicht das Rendern mit den Standard‑Optionen nicht aus, weshalb GroupDocs.Viewer ein umfangreiches Set an Eigenschaften bereitstellt; damit kann jeder Benutzer das Rendering exakt an seine Bedürfnisse anpassen.
Siehe auch
- Excel‑ und Apple Numbers‑Spreadsheets als HTML, PDF und Bilddateien rendern
- Ein Arbeitsblatt in Seiten aufteilen
- Spreadsheet‑Rendering‑Optionen festlegen
Kostenlose Testversion
Sie können eine kostenlose Testversion von GroupDocs.Viewer für .NET unter releases.groupdocs.com herunterladen. Außerdem können Sie hier eine temporäre Lizenz erwerben, um alle Funktionen uneingeschränkt zu testen: hier.