Praca z arkuszami kalkulacyjnymi w GroupDocs.Viewer dla .NET

Przegląd

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

Renderowanie skoroszytu, otwartego w MS Excel, do formatu HTML

Podstawowe użycie

Przede wszystkim musimy porozmawiać o opcjach. W publicznym API istnieje oddzielna klasa: SpreadsheetOptions w przestrzeni nazw GroupDocs.Viewer.Options. Klasa ta jest przeznaczona specjalnie do dostosowywania renderowania rodziny formatów arkuszy kalkulacyjnych. Jest dostępna dla wszystkich czterech opcji widoku poprzez właściwość SpreadsheetOptions w:

HtmlViewOptions.SpreadsheetOptions przy renderowaniu dokumentu arkusza do HTML,
PdfViewOptions.SpreadsheetOptions przy renderowaniu dokumentu arkusza do PDF,
PngViewOptions.SpreadsheetOptions przy renderowaniu dokumentu arkusza do PNG,
JpgViewOptions.SpreadsheetOptions przy renderowaniu dokumentu arkusza do JPEG.

Jeśli nie zostanie podana explicite, właściwość SpreadsheetOptions ma domyślną, niejawnie ustawioną wartość instancji klasy SpreadsheetOptions, której wyjaśnienie pojawi się później w tym artykule.

Na pierwszy rzut oka renderowanie dokumentu arkusza przy użyciu GroupDocs.Viewer jest bardzo proste i podobne do wszystkich innych formatów — tworzymy instancję ViewOptions, tworzymy obiekt Viewer z określonym wejściowym dokumentem arkusza i wywołujemy metodę Viewer.View(viewOptions). Poniższy przykład kodu demonstruje renderowanie jednego pliku arkusza do wszystkich 4 formatów wyjściowych: HTML, PDF, PNG i JPEG. Zwróć uwagę, że oprócz tworzenia instancji klas opcji nie ma żadnego dodatkowego dostrajania dotyczącego 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 porozmawiamy o arkuszach. Każdy arkusz posiada przynajmniej jeden arkusz roboczy. W większości programów przetwarzających tabele, takich jak Microsoft Excel, arkusze są reprezentowane jako karty. Niektóre formaty arkuszy mogą mieć tylko jeden arkusz; dotyczy to na przykład wszystkich tekstowych formatów rozdzielonych separatorami (CSV, TSV itp.).

Domyślnie GroupDocs.Viewer renderuje wszystkie arkusze znajdujące się w danym skoroszycie. Można to jednak 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. Ten parametr jest uniwersalny i ma zastosowanie do wszystkich obsługiwanych formatów, które posiadają strony, ale w kontekście rodziny formatów arkuszy kalkulacyjnych opisuje dokładnie numery arkuszy do wyświetlenia.

Pamiętaj, że numeracja stron (a w szczególności arkuszy) rozpoczyna się od 1, a nie od 0.

Poniższy przykład pokazuje, jak wyrenderować 1‑szy i 3‑ci arkusz do PNG w skoroszycie zawierającym 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);
}

Dzielnie arkuszy na strony

GroupDocs.Viewer renderuje dokumenty na strony, gdzie pod „stroną” rozumiemy pewien prostokątny obszar o stosunkowo małym rozmiarze, porównywalnym do 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. Dostępnych jest 5 różnych metod, które są 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()

Najprostsze rozwiązanie — wyłączenie dzielenia i dopasowanie rozmiaru strony tak, aby pomieściła całą zawartość arkusza. To dobre rozwiązanie, gdy wiadomo, że arkusz ma niewielki rozmiar. Jednak przy bardzo dużym arkuszu może to prowadzić do katastrofalnych rezultatów. Na przykład przy renderowaniu do HTML wynikowy dokument może mieć setki MiB, co utrudnia jego przeglądanie w przeglądarkach. Przy renderowaniu do JPEG problem może być jeszcze poważniejszy, jeśli szerokość lub wysokość przekroczy maksymalny limit 65 535 pikseli. Dlatego używaj tego trybu świadomie.

Dziel arkusz według podziałów strony

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel samodzielnie wstawia automatyczne podziały stron w zależności od rozmiaru papieru i ustawień strony, takich jak orientacja i marginesy. Przełączając się na zakładkę Widok i wybierając tryb Podgląd podziałów stron, zobaczysz niebieskie linie dzielące cały arkusz na prostokątne fragmenty, oznaczone kolejno jako „Strona 1”, „Strona 2” itp. To właśnie Excel „sugeruje” podział arkusza na strony.

Ta metoda sprawia, że GroupDocs.Viewer podąża za podziałami strony wprowadzonymi w Excelu.

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

Renderowanie tylko obszaru wydruku

SpreadsheetOptions.ForRenderingPrintArea()

Oprócz podziałów stron, Excel posiada pojęcie obszaru wydruku. Obszar wydruku to jeden lub więcej zakresów komórek, które mają być drukowane; zawartość spoza tego obszaru nie będzie drukowana. Aby dodać zakres komórek do obszaru wydruku, przejdź do zakładki Układ strony, kliknij przycisk Obszar wydruku i wybierz Ustaw obszar wydruku (zobacz zrzut ekranu poniżej). Aby dodać kolejny zakres, zaznacz go, kliknij Obszar wydruku i wybierz Dodaj do obszaru wydruku. W trybie Podgląd podziałów stron zobaczysz wszystkie zakresy w obszarze wydruku.

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

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer posiada unikalną cechę — łączenie obszaru wydruku i podziałów strony w jednym trybie. W tym przypadku Viewer uwzględnia wszystkie zakresy obszaru wydruku oraz podziały stron w arkuszu i stosuje je jednocześnie do podzielenia arkusza na strony.

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

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

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 ani obszarów wydruku, 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 wierszy a dzieleniem 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 zostanie dzielenie wyłącznie według wierszy. Jeśli użyta zostanie druga wersja z dwoma parametrami, włączone zostanie dzielenie według wierszy i kolumn.

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

Dostosowywanie dodatkowych opcji

Wszystko, co opisano powyżej, jest niezbędne i wystarczające do renderowania arkuszy przy pomocy GroupDocs.Viewer. Istnieje jednak 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

Gdy MS Excel lub podobny program otwiera dokument arkusza, 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 dokumentu. Można to zmienić, ustawiając właściwość RenderHeadings na true. Po włączeniu nagłówki wierszy i kolumn będą widoczne w dokumencie wyjściowym, co pokazuje poniższy zrzut ekranu.

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 danych w danym programie. Ustawiając właściwość RenderGridLines na true, można zasymulować zachowanie Excela. Po włączeniu linie siatki będą widoczne w dokumencie wyjściowym, co widać na poniższym zrzucie ekranu.

Kontrola przepełniania tekstu w komórce

Często zdarza się, że tekst w komórce nie mieści się w jej granicach. 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 przyjmuje wartość typu o tej samej nazwie, będącą wyliczeniem (enum) z czterema możliwymi opcjami, opisanymi poniżej.

OverlayIfNextIsEmpty

Domyślnie SpreadsheetOptions.TextOverflowMode ma wartość OverlayIfNextIsEmpty, co naśladuje domyślne zachowanie Excela. Tekst może przelewać się do sąsiednich komórek, ale tylko wtedy, gdy te komórki są puste. Jeśli są wypełnione, tekst zostaje obcięty.

Na powyższym zrzucie ekranu widać plik HTML wygenerowany z pliku XLSX z ustawioną wartością OverlayIfNextIsEmpty. Zauważ komórkę „B2” — tekst w niej jest obcięty, ponieważ komórka „C2” nie jest pusta. Natomiast komórka „C3” ma długi tekst, który przelewa się na „D2” i „E2”, ponieważ te są puste.

Overlay

Wartość TextOverflowMode.Overlay działa podobnie, ale jest bardziej agresywna: długi tekst zawsze przelewa się do sąsiednich komórek, niezależnie od tego, czy są puste. Jeśli są wypełnione, ich zawartość zostaje nadpisana.

Zrzut ekranu pokazuje, jak to działa. Długi tekst z komórki „B2” przelewa się na „C2”, „D2”, „E2”, „F2”. W wyniku tego oryginalny tekst w komórkach „C2” i „F2” zostaje usunięty.

HideText

Tryb TextOverflowMode.HideText działa odwrotnie do Overlay — zamiast przelewania tekst jest zawsze obcinany, niezależnie od dostępnego miejsca w sąsiednich komórkach.

Na zrzucie ekranu widać komórkę „C3” — mimo że w sąsiednich komórkach „D3” itp. jest wolne miejsce, tekst zostaje bezwarunkowo obcięty.

AutoFitColumn

Wartość TextOverflowMode.AutoFitColumn rozwiązuje problem inaczej — zwiększa szerokość kolumny, aby pomieścić cały tekst. Niezależnie od długości tekstu w konkretnej komórce, szerokość kolumny, w której się ona znajduje, zostaje zwiększona, aby pomieścić cały ciąg znaków.

Zrzut ekranu pokazuje działanie tej opcji. Oczywiście podejście to nie zawsze jest pożądane, zwłaszcza przy bardzo długim tekście, ponieważ strona może stać się niezwykle szeroka, co skutkuje niechcianym przewijaniem w poziomie.

Renderowanie ukrytych wierszy i kolumn

Microsoft Excel i inne programy pozwalają ukrywać wybrane wiersze i kolumny. Domyślnie GroupDocs.Viewer nie renderuje takich elementów, ale zachowanie to można zmienić. Ustawiając właściwości ViewOptions.SpreadsheetOptions.RenderHiddenRows oraz ViewOptions.SpreadsheetOptions.RenderHiddenColumns na true, ukryte wiersze i kolumny będą widoczne w pliku wyjściowym przy renderowaniu do 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, ale można to zmienić, ustawiając właściwość RenderHiddenPages na true. Należy zaznaczyć, że w przeciwieństwie do wcześniej opisanych właściwości, RenderHiddenPages znajduje się nie w SpreadsheetOptions, a w abstrakcyjnej klasie BaseViewOptions, wspólnej dla wszystkich opcji widoku.

Pomijanie pustych wierszy i kolumn

Niektóre arkusze są „rzadkie” — zawierają wiele pustych komórek, które zajmują niepotrzebnie miejsce. GroupDocs.Viewer oferuje funkcję pomijania pustych wierszy i kolumn podczas renderowania. Jeśli funkcja jest włączona, puste wiersze i/lub kolumny zostają wykluczone z wynikowego HTML, PDF, PNG i JPEG. Za tę funkcję odpowiadają właściwości typu logicznego SpreadsheetOptions.SkipEmptyRows oraz SpreadsheetOptions.SkipEmptyColumns.

Zrzut ekranu pokazuje włączone opcje SkipEmptyRows i SkipEmptyColumns.

Renderowanie lub ukrywanie komentarzy komórek

Komórki w arkuszu mogą zawierać komentarze, które domyślnie są renderowane przez GroupDocs.Viewer. Można to wyłączyć, ustawiając właściwość BaseViewOptions.RemoveComments na true — wówczas żadne komentarze nie będą wyświetlane. Warto pamiętać, że ta właściwość znajduje się w klasie BaseViewOptions, a nie w SpreadsheetOptions.

Zrzut ekranu pokazuje renderowanie pliku XLSX z komentarzami komórek do formatu PNG przy użyciu domyślnych opcji — komentarz w komórce „E2” jest widoczny w wygenerowanym pliku PNG.

Ustawianie marginesów arkusza w wyjściowych stronach PDF

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

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

Poniższy fragment kodu pokazuje 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 obraz ilustruje rezultat:

Ustawianie marginesów arkusza w wyjściowych stronach PDF

Wnioski

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

Zobacz także

Uzyskaj darmową wersję próbną

Możesz pobrać darmową wersję próbną GroupDocs.Viewer dla .NET z releases.groupdocs.com. Tym samym możesz także uzyskać tymczasową licencję, by wypróbować wszystkie funkcje i możliwości bez ograniczeń, pod tym linkiem: here.

Przegląd#

Podstawowe użycie#

Dzielnie arkuszy na strony#

Renderowanie całego arkusza na jednej stronie#

Dziel arkusz według podziałów strony#

Renderowanie tylko obszaru wydruku#

Renderowanie obszaru wydruku i dzielenie według podziałów strony#

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

Dostosowywanie dodatkowych opcji#

Renderowanie nagłówków wierszy i kolumn#

Renderowanie linii siatki arkusza#

Kontrola przepełniania tekstu w komórce#

OverlayIfNextIsEmpty#

Overlay#

HideText#

AutoFitColumn#

Renderowanie ukrytych wierszy i kolumn#

Renderowanie ukrytych arkuszy#

Pomijanie pustych wierszy i kolumn#

Renderowanie lub ukrywanie komentarzy komórek#

Ustawianie marginesów arkusza w wyjściowych stronach PDF#

Wnioski#

Zobacz także#

Uzyskaj darmową wersję próbną#