Przegląd

Spreadsheet documents to dokumenty zawierające dane w formie tabelarycznej — w wierszach i kolumnach. Są również znane jako workbooks. Istnieje wiele formatów dokumentów arkuszy kalkulacyjnych — Office Open XML (np. XLSX, XLSM itp.), Microsoft Excel Binary File Format (XLS, XLT), format OpenDocument Spreadsheet (ODS, FODS, OTS), formaty tekstowe oparte na separatorach (CSV, TSV itp.) i tak dalej. Wszystkie one tworzą tak zwaną rodzinę formatów arkuszy kalkulacyjnych. GroupDocs.Viewer obsługuje prawie wszystkie formaty arkuszy kalkulacyjnych przy imporcie i umożliwia renderowanie (konwersję) ich do HTML, PDF, PNG i JPEG. Ten artykuł wyjaśnia, jak to zrobić, jakie opcje są dostępne oraz kiedy i dlaczego należy ich używać.

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

Podstawowe użycie

Na początek musimy porozmawiać o opcjach. W publicznym API istnieje osobna klasa: SpreadsheetOptions w przestrzeni nazw GroupDocs.Viewer.Options. Klasa ta została zaprojektowana specjalnie do dostosowywania renderowania rodziny formatów arkuszy kalkulacyjnych. Jest dostępna dla wszystkich czterech opcji widoku poprzez właściwość SpreadsheetOptions w:

Jeśli nie zostanie określona explicite, właściwość SpreadsheetOptions ma domyślną, niejawnie ustawioną wartość instancji klasy SpreadsheetOptions, którą wyjaśnimy później w tym artykule.

Na pierwszy rzut oka renderowanie dokumentu arkusza kalkulacyjnego przy użyciu GroupDocs.Viewer jest bardzo proste i podobne do wszystkich innych formatów — tworzymy instancję ViewOptions, tworzymy instancję Viewer z określonym wejściowym dokumentem arkusza kalkulacyjnego i wywołujemy metodę Viewer.View(viewOptions). Poniższy przykład kodu demonstruje renderowanie pojedynczego pliku arkusza kalkulacyjnego do wszystkich 4 formatów wyjściowych: HTML, PDF, PNG i JPEG. Zauważ, że poza tworzeniem instancji klas opcji nie ma żadnego dostrajania specyficznego dla arkuszy, więc wszystkie opcje arkusza mają wartości domyślne.

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

Teraz porozmawiajmy o arkuszach. Każdy arkusz kalkulacyjny ma przynajmniej jeden arkusz. W większości programów do przetwarzania tabel, takich jak Microsoft Excel, arkusze są reprezentowane jako zakładki. Niektóre formaty arkuszy mogą mieć tylko jeden arkusz; dotyczy to na przykład wszystkich formatów tekstowych opartych na separatorach (CSV, TSV itp.).

Domyślnie GroupDocs.Viewer renderuje wszystkie arkusze znajdujące się w podanym pliku. Można to zmienić. Metoda Viewer.View() ma przeciążenie, które przyjmuje zestaw numerów stron jako drugi parametr — Int32[] pageNumbers. Gdy ten parametr jest użyty, renderowane będą tylko podane strony. Parametr ten jest uniwersalny i stosowany do wszystkich obsługiwanych formatów, które mają strony, ale w kontekście rodziny formatów arkuszy kalkulacyjnych opisuje dokładnie numery arkuszy do wyświetlenia.

Należy pamiętać, że numeracja stron (ogólnie) i numeracja arkuszy (szczególnie) jest numeracją zaczynającą się od 1, a nie od 0, więc zaczyna się od „1”, a nie od „0”.

Poniższy przykład pokazuje, jak wyrenderować 1‑szy i 3‑ci arkusz do PNG w arkuszu, który ma 3 arkusze.

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

Dzielenie arkuszy na strony

GroupDocs.Viewer renderuje dokumenty na strony, gdzie pod pojęciem strony rozumiemy pewien prostokątny obszar stosunkowo małego rozmiaru, porównywalny do obszaru wyświetlacza lub kartki A4. Z drugiej strony arkusze mogą być bardzo duże. Na przykład przestarzały format XLS obsługuje maksymalnie 256 kolumn i 65 536 wierszy, podczas gdy nowszy format XLSX (Office Open XML Workbook) oraz Microsoft Excel obsługują do 16 384 kolumn i 1 048 576 wierszy. „Dopasowanie” arkuszy do stron jest kluczowym elementem renderowania arkuszy przy użyciu GroupDocs.Viewer. Aby dopasować arkusz do jednej lub kilku stron, GroupDocs.Viewer wykonuje dzielenie arkusza — arkusz jest podzielony na wiele prostokątnych fragmentów, a każdy z nich umieszczany jest na osobnej stronie. Istnieje 5 różnych metod, które są wymienione i opisane poniżej.

Ważne — wszystkie te metody dzielenia są określane w ten sam sposób — przy użyciu konkretnej statycznej metody (metody fabrycznej), która tworzy instancję klasy SpreadsheetOptions.

Renderowanie całego arkusza na jednej stronie

SpreadsheetOptions.ForOnePagePerSheet()

Najprostszy sposób — wyłączyć dzielenie i dostosować rozmiar strony tak, aby pomieściła całą zawartość całego arkusza. To dobre rozwiązanie, gdy wiadomo, że arkusz ma mały rozmiar. Jednakże, jeśli arkusz jest naprawdę duży, podejście to może dawać fatalne wyniki. W szczególności przy renderowaniu do formatu HTML wynikowy dokument HTML może być ogromny, dziesiątki lub nawet setki MiB, co może powodować problemy przy przeglądaniu tak dużych plików w przeglądarkach internetowych. Przy renderowaniu do formatu JPEG sytuacja może być jeszcze gorsza, jeśli szerokość lub wysokość przekroczy maksymalny limit 65 535 pikseli. Używaj tego trybu świadomie.

Render worksheet on one page

Dzielenie arkusza według podziałów stron

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel samodzielnie dodaje automatyczne podziały stron w zależności od rozmiaru papieru i ustawień strony, takich jak orientacja i marginesy. Jeśli przejdziesz do zakładki „View” i wybierzesz tryb „Page Break Preview”, zobaczysz niebieskie linie dzielące cały obszar arkusza na prostokątne fragmenty, z których każdy jest oznaczony jako „Page 1”, „Page 2” itd. Tak Excel „sugeruje” podział arkusza na strony.

Ta metoda sprawia, że GroupDocs.Viewer podąża za Microsoft Excel i dzieli arkusze zgodnie z podziałami stron, tak jak robi to Excel.

Warto wspomnieć, że ta opcja — dzielenie arkusza według podziałów stron — jest domyślną opcją właściwości BaseViewOptions.SpreadsheetOptions, więc przy tworzeniu instancji klasy opcji widoku opcja „ForRenderingByPageBreaks()” jest wybrana domyślnie.

Renderowanie tylko obszaru wydruku

SpreadsheetOptions.ForRenderingPrintArea()

Oprócz podziałów stron, Microsoft Excel posiada pojęcie „Print Area”. Print Area to jeden lub więcej zakresów komórek w arkuszu, które są wyznaczone do drukowania; wszelka zawartość poza tym obszarem nie jest drukowana. Aby dodać zakres komórek do Print Area, przejdź do zakładki „Page Layout”, kliknij przycisk „Print Area”, a następnie wybierz pozycję „Set Print Area” (zobacz zrzut ekranu poniżej). Aby dodać kolejny zakres, zaznacz nowy zakres, kliknij przycisk „Print Area” i wybierz „Add to Print Area”. W trybie „Page Break Preview” możesz zobaczyć wszystkie zakresy w Print Area.

Render only print area

Renderowanie obszaru wydruku i dzielenie według podziałów stron

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer posiada unikalną funkcję — łączenie Print Area i podziałów stron w jednym trybie. W tym przypadku GroupDocs.Viewer uwzględnia wszystkie zakresy komórek Print Area oraz podziały stron w arkuszu i stosuje je jednocześnie, aby podzielić arkusz na strony.

Na poniższym zrzucie ekranu czerwona linia oznacza Print Area, a niebieska linia — podziały stron.

Render print area and split by page breaks

Ręczne dzielenie arkusza na strony według wierszy i kolumn

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

Czasami żadna z opisanych wyżej metod dzielenia nie jest akceptowalna, lub arkusz ma format, który nie obsługuje podziałów stron i Print Area, np. tekstowy CSV. W takich przypadkach GroupDocs.Viewer pozwala ręcznie określić liczbę wierszy i/lub kolumn, które mają znajdować się na każdej stronie. Krótko mówiąc, różnica między dzieleniem wyłącznie według wierszy a dzieleniem według wierszy i kolumn jest zilustrowana na poniższym zrzucie ekranu.

Jeśli użyta zostanie pierwsza przeciążona metoda ForSplitSheetIntoPages z jednym parametrem, włączone zostaje dzielenie wyłącznie według wierszy. Jeśli użyta zostanie druga metoda z dwoma parametrami, włączone zostaje dzielenie według wierszy i kolumn.

Split worksheet into pages manually by rows and columns

Dostosowywanie dodatkowych opcji

Wszystko, co opisano powyżej, jest niezbędne i wystarczające do renderowania arkuszy przy użyciu GroupDocs.Viewer. Jednak istnieje wiele dodatkowych opcji, które nie są obowiązkowe, ale pozwalają użytkownikom jeszcze lepiej dostosować wynik renderowania.

Niektóre z tych opcji są reprezentowane jako właściwości klasy SpreadsheetOptions, dostępnej jako właściwość SpreadsheetOptions klasy opcji widoku. Inne znajdują się w abstrakcyjnej klasie ViewOptions, wspólnej dla wszystkich 4 trybów renderowania.

Renderowanie nagłówków wierszy i kolumn

Kiedy MS Excel lub podobny program do przetwarzania tabel otwiera dokument arkusza kalkulacyjnego, wyświetla nagłówki kolumn i wierszy: kolumny są oznaczone literami (A, B, C, AA, AB, …), a wiersze numerami (1, 2, 3, …, 1048576). Podczas renderowania GroupDocs.Viewer domyślnie nie wyświetla tych nagłówków, ponieważ są one częścią interfejsu programu, a nie samego dokumentu. Można to zmienić przy pomocy właściwości RenderHeadings typu bool. Domyślnie jest wyłączona (false), ale po włączeniu (true) nagłówki wierszy i kolumn będą obecne w dokumencie wyjściowym, co widać na poniższym zrzucie ekranu.

Render row and column headings

Renderowanie linii siatki arkusza

Koncepcja tej opcji jest bardzo podobna do poprzedniej. Domyślnie GroupDocs.Viewer nie wyświetla linii siatki między komórkami, ponieważ nie są one częścią samego arkusza, a jedynie sposobem prezentacji tabeli w konkretnym programie. Jednak przy użyciu właściwości RenderGridLines typu bool można naśladować zachowanie MS Excel. Przypisz wartość true do właściwości SpreadsheetOptions.RenderGridLines, a linie siatki będą widoczne w dokumencie wyjściowym, jak pokazano na zrzucie ekranu poniżej.

Render worksheet gridlines

Kontrola przepełnienia tekstu w komórce

Często zdarza się, że tekst nie mieści się w granicach komórki. Jak prawidłowo wyświetlić taki tekst? GroupDocs.Viewer udostępnia specjalną właściwość SpreadsheetOptions.TextOverflowMode rozwiązującą ten problem. Właściwość TextOverflowMode ma typ o tej samej nazwie i jest typem wyliczeniowym z 4 możliwymi wartościami, opisanymi poniżej.

OverlayIfNextIsEmpty

Domyślnie właściwość SpreadsheetOptions.TextOverflowMode ma wartość OverlayIfNextIsEmpty, co naśladuje domyślne zachowanie Microsoft Excel. W skrócie, pozwala to tekstowi wyjść poza granice komórki do sąsiednich komórek, ale tylko wtedy, gdy te są puste. Jeśli sąsiednie komórki nie są puste, tekst jest obcinany.

OverlayIfNextIsEmpty enum value

Powyższy zrzut ekranu pokazuje plik HTML wyrenderowany z pliku XLSX z ustawioną wartością OverlayIfNextIsEmpty. Zwróć uwagę na komórkę „B2” — ma długi tekst, który jest obcięty, ponieważ komórka „C2” nie jest pusta. Natomiast komórka „C3” ma długi tekst, który nie mieści się, ale przelewa się na komórki „D2” i „E2”, ponieważ są one puste.

Overlay

Wartość TextOverflowMode.Overlay jest nieco podobna do poprzedniej, ale można ją uznać za bardziej agresywną: długi tekst, który nie mieści się w granicach oryginalnej komórki, zawsze przelewa się, niezależnie od zawartości sąsiednich komórek. Jeśli sąsiednie komórki również zawierają tekst lub inne dane, zostaną one nadpisane.

Overlay enum value

Zrzut ekranu powyżej demonstruje działanie tej opcji. Długi tekst z komórki „B2” przelewa się na sąsiednie komórki „C2”, „D2”, „E2”, „F2”. W rezultacie oryginalny tekst w komórkach „C2” i „F2” zostaje usunięty.

HideText

Tryb TextOverflowMode.HideText działa odwrotnie do opisanej wyżej opcji Overlay — zamiast przelewania tekst jest ostatecznie obcinany, jeśli nie mieści się w granicach własnej komórki, niezależnie od tego, czy w sąsiednich komórkach jest wolne miejsce.

HideText enum value

Na powyższym zrzucie ekranu widać to na przykładzie komórki „C3” — mimo że w sąsiednich komórkach „D3” i kolejnych jest wolne miejsce, tekst jest bezwarunkowo obcinany.

AutoFitColumn

Wartość TextOverflowMode.AutoFitColumn rozwiązuje problem w inny sposób — zwiększa szerokość kolumny, aby dopasować tekst dowolnej komórki. Niezależnie od tego, jak długi jest tekst w konkretnej komórce, szerokość kolumn, w których ta komórka się znajduje, zostanie zwiększona, aby pomieścić cały ciąg znaków.

AutoFitColumn enum value

Zrzut ekranu powyżej pokazuje, jak to działa. Oczywiście takie podejście może nie być odpowiednie w niektórych przypadkach, szczególnie gdy tekst w komórkach jest bardzo długi — spowoduje to bardzo szeroką stronę z uciążliwym przewijaniem w poziomie.

Renderowanie ukrytych wierszy i kolumn

Microsoft Excel i inne programy do przetwarzania tabel pozwalają ukrywać wybrane wiersze i kolumny. Domyślnie GroupDocs.Viewer nie renderuje takich wierszy i kolumn, ale zachowanie to można zmienić. Właściwości ViewOptions.SpreadsheetOptions.RenderHiddenRows oraz ViewOptions.SpreadsheetOptions.RenderHiddenColumns, ustawione na true, pozwalają wyświetlić ukryte wiersze i kolumny w pliku wyjściowym przy renderowaniu arkusza w formatach HTML, PDF, PNG lub JPEG.

Renderowanie ukrytych arkuszy

Podobnie jak ukryte wiersze i kolumny, plik arkusza może zawierać jeden lub więcej ukrytych arkuszy. Domyślnie GroupDocs.Viewer nie renderuje ukrytych arkuszy. Można to zmienić, używając właściwości RenderHiddenPages i ustawiając jej wartość na true. Warto zaznaczyć, że w przeciwieństwie do wcześniej opisanych właściwości, RenderHiddenPages znajduje się nie w SpreadsheetOptions, lecz w abstrakcyjnej klasie BaseViewOptions, wspólnej dla wszystkich opcji widoku.

Pomijanie pustych wierszy i kolumn

Niektóre arkusze są „rzadkie” — zawierają wiele pustych pól, które mogą zajmować niepotrzebnie dużo miejsca. GroupDocs.Viewer posiada funkcję pomijania pustych wierszy i kolumn podczas renderowania. Jeśli funkcja ta jest włączona, puste wiersze i/lub kolumny są wykluczane z wynikowego HTML, PDF, PNG i JPEG. Za tę funkcję odpowiadają właściwości boolowskie SpreadsheetOptions.SkipEmptyRows oraz SpreadsheetOptions.SkipEmptyColumns.

Skip empty rows and columns

Zrzut ekranu powyżej pokazuje, że zarówno SkipEmptyRows, jak i SkipEmptyColumns są włączone.

Renderowanie lub ukrywanie komentarzy komórek

Komórki w dokumencie arkusza mogą mieć komentarze i domyślnie GroupDocs.Viewer renderuje je wszystkie. Można to wyłączyć, używając właściwości BaseViewOptions.RemoveComments. Ustawiając jej wartość na true, żadne komentarze nie będą renderowane. Należy zauważyć, że ta właściwość znajduje się w klasie BaseViewOptions, a nie w SpreadsheetOptions.

Render or hide cell comments

Zrzut ekranu powyżej demonstruje renderowanie pliku XLSX z komentarzami komórek do formatu PNG przy użyciu domyślnych opcji — komentarz dla komórki „E2” jest widoczny w wynikowym pliku PNG.

Ustawianie marginesów arkusza w wyjściowych stronach PDF

Podczas renderowania arkuszy do formatu PDF można kontrolować marginesy stron — odległość w centymetrach od krawędzi strony do treści. Istnieją 4 właściwości kontrolujące marginesy górny, prawy, dolny i lewy:

Domyślnie wszystkie te 4 właściwości mają wartości ujemne, co oznacza, że domyślne marginesy są stosowane przez GroupDocs.Viewer. Można jednak ustawić te wartości explicite. Należy podkreślić, że marginesy stron mają zastosowanie wyłącznie, gdy docelowym formatem jest PDF.

Poniższy fragment kodu demonstruje tworzenie obiektu PdfViewOptions, ustawianie wszystkich 4 marginesów i renderowanie 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);
}

Poniższy obrazek przedstawia rezultat:

Set worksheet margins in the output PDF pages

Podsumowanie

Formaty arkuszy kalkulacyjnych są dość złożone, a dokumenty mogą mieć bardzo różną zawartość pod względem typu i długości. W wielu przypadkach niemożliwe jest renderowanie złożonego dokumentu arkusza kalkulacyjnego do określonego formatu przy użyciu domyślnych opcji, dlatego GroupDocs.Viewer udostępnia tak obszerny zestaw właściwości; dzięki nim każdy użytkownik będzie mógł dostosować renderowanie do własnych potrzeb.

Zobacz także

Pobierz darmową wersję próbną

Możesz pobrać darmową wersję próbną GroupDocs.Viewer dla .NET z releases.groupdocs.com. Możesz także uzyskać tymczasową licencję, aby wypróbować wszystkie funkcje i możliwości bez ograniczeń, tutaj.