Overview

Spreadsheet documents adalah dokumen yang berisi data dalam bentuk tabel — di dalam baris dan kolom. Mereka juga dikenal sebagai workbook. Terdapat banyak format dokumen spreadsheet — Office Open XML (seperti XLSX, XLSM, dll.), Microsoft Excel Binary File Format (XLS, XLT), format OpenDocument Spreadsheet (ODS, FODS, OTS), format berbasis teks yang dipisahkan oleh pemisah (CSV, TSV dll.) dan seterusnya. Semua ini membentuk apa yang disebut keluarga format Spreadsheet. GroupDocs.Viewer mendukung hampir semua format spreadsheet pada proses impor dan memungkinkan merender (mengonversi) mereka ke HTML, PDF, PNG, dan JPEG. Artikel ini menjelaskan cara melakukannya, opsi apa yang tersedia, serta kapan dan mengapa opsi‑opsi tersebut harus digunakan.

Merender sebuah workbook, dibuka di MS Excel, ke format HTML

Basic usage

Pertama‑tama kita perlu membahas tentang opsi. Ada kelas terpisah dalam API publik: SpreadsheetOptions di dalam GroupDocs.Viewer.Options. Kelas ini dirancang khusus untuk menyesuaikan proses render keluarga format Spreadsheet. Kelas ini dapat diakses melalui properti SpreadsheetOptions pada keempat opsi view:

Jika tidak ditentukan secara eksplisit, properti SpreadsheetOptions memiliki nilai implisit default berupa instance kelas SpreadsheetOptions, yang akan dijelaskan lebih lanjut dalam artikel ini.

Secara sekilas, merender dokumen Spreadsheet dengan GroupDocs.Viewer sangat mudah dan mirip dengan semua format lainnya — buat instance ViewOptions, buat instance Viewer dengan dokumen Spreadsheet input yang ditentukan, dan panggil metode Viewer.View(viewOptions). Contoh kode berikut menunjukkan cara merender satu file Spreadsheet input ke keempat format output: HTML, PDF, PNG, dan JPEG. Perlu dicatat bahwa selain membuat instance kelas opsi, tidak ada penyesuaian khusus untuk spreadsheet, sehingga semua opsi spreadsheet menggunakan nilai default.

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

Sekarang mari kita bahas tentang worksheets. Setiap spreadsheet memiliki setidaknya satu worksheet. Pada kebanyakan perangkat lunak pengolah tabel seperti Microsoft Excel, worksheet ditampilkan sebagai tab. Beberapa format spreadsheet mungkin hanya memiliki satu worksheet; hal ini termasuk, misalnya, semua format berbasis teks yang dipisahkan oleh pemisah (CSV, TSV dll.).

Secara default GroupDocs.Viewer merender semua worksheet di dalam spreadsheet yang diberikan. Namun hal ini dapat diubah. Metode Viewer.View() memiliki overload yang menerima sekumpulan nomor halaman sebagai parameter ke‑2 — Int32[] pageNumbers. Ketika parameter ini digunakan, hanya halaman‑halaman tersebut yang akan dirender. Parameter ini bersifat universal dan diterapkan pada semua format yang mendukung halaman, tetapi dalam konteks keluarga format Spreadsheet, ia menggambarkan nomor worksheet yang akan ditampilkan.

Perlu dicatat bahwa penomoran halaman secara umum dan penomoran worksheet secara khusus bersifat berbasis 1, bukan 0, sehingga dimulai dari “1”, bukan “0”.

Contoh di bawah ini menunjukkan cara merender worksheet ke‑1 dan ke‑3 ke PNG pada spreadsheet yang memiliki 3 worksheet.

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

Splitting worksheets into pages

GroupDocs.Viewer merender dokumen ke dalam halaman, di mana “halaman” dimaknai sebagai area persegi panjang berukuran relatif kecil, sebanding dengan area tampilan atau kertas A4. Di sisi lain, worksheet dapat sangat besar. Khususnya, format lama XLS mendukung maksimum 256 kolom dan 65 536 baris, sementara format yang lebih baru XLSX (Office Open XML Workbook) dan Microsoft Excel keduanya mendukung hingga 16 384 kolom dan 1 048 576 baris. “Memuat” worksheet ke dalam halaman merupakan bagian krusial dalam proses render spreadsheet dengan GroupDocs.Viewer. Agar worksheet muat ke halaman, GroupDocs.Viewer melakukan splitting worksheet — worksheet dibagi menjadi beberapa potongan persegi panjang, dan masing‑masing ditempatkan pada halaman terpisah. Terdapat 5 metode berbeda, yang dijabarkan di bawah ini.

Hal yang penting — semua metode splitting ini ditentukan dengan cara yang sama — menggunakan metode statis tertentu (factory method) yang menghasilkan instance kelas SpreadsheetOptions.

Render whole worksheet on one page

SpreadsheetOptions.ForOnePagePerSheet()

Cara paling mudah dan sederhana — menonaktifkan splitting dan menyesuaikan ukuran halaman agar menampung seluruh konten worksheet. Ini cocok bila sudah diketahui bahwa worksheet berukuran kecil. Namun, bila worksheet sangat besar, pendekatan ini dapat menghasilkan hasil yang buruk. Khususnya, saat merender ke format HTML, dokumen HTML yang dihasilkan dapat berukuran sangat besar, puluhan atau bahkan ratusan MiB, yang dapat menyebabkan masalah saat menampilkan file besar tersebut di peramban web. Saat merender ke format JPEG, masalah bisa lebih parah bila lebar atau tinggi melebihi batas maksimum 65 535 piksel. Jadi gunakan mode ini dengan pertimbangan matang.

Merender worksheet pada satu halaman

Split worksheet by page breaks

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel secara otomatis menambahkan pemisah halaman (page breaks) berdasarkan ukuran kertas dan pengaturan halaman, seperti orientasi dan margin. Jika Anda beralih ke tab “View” dan masuk ke mode “Page Break Preview”, Anda akan melihat garis biru yang membagi seluruh area worksheet menjadi potongan persegi panjang, masing‑masing berlabel “Page 1”, “Page 2”, dan seterusnya. Inilah cara Microsoft Excel “menyarankan” pemisahan worksheet ke halaman.

Dengan metode ini GroupDocs.Viewer mengikuti Microsoft Excel dan memisahkan worksheet menurut page break, sebagaimana yang dilakukan Excel.

Perlu disebutkan bahwa opsi ini — memisahkan worksheet berdasarkan page break — merupakan opsi default dari properti BaseViewOptions.SpreadsheetOptions. Jadi ketika Anda membuat instance kelas view options, opsi “ForRenderingByPageBreaks()” dipilih secara otomatis.

Render only print area

SpreadsheetOptions.ForRenderingPrintArea()

Selain page break, Microsoft Excel memiliki konsep “Print Area”. Print Area sebenarnya merupakan satu atau lebih rentang sel dalam worksheet yang ditetapkan untuk dicetak, sementara konten di luar Print Area tidak akan dicetak sama sekali. Untuk menambahkan rentang sel ke Print Area, buka tab “Page Layout”, klik tombol “Print Area”, lalu pilih “Set Print Area” (lihat screenshot di bawah). Untuk menambahkan rentang sel lain, pilih rentang baru tersebut, klik tombol “Print Area”, kemudian pilih “Add to Print Area”. Pada mode “Page Break Preview” Anda dapat melihat semua rentang sel dalam Print Area.

Merender hanya Print Area

Render print area and split by page breaks

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer memiliki fitur unik — menggabungkan Print Area dan page break dalam satu mode. Dalam kasus ini GroupDocs.Viewer memperhitungkan semua rentang sel pada Print Area serta page break pada worksheet dan menerapkannya sekaligus untuk memisahkan worksheet ke halaman.

Pada screenshot berikut garis merah menunjukkan Print Area, dan garis biru menunjukkan page break.

Merender Print Area dan memisahkan berdasarkan page break

Split worksheet into pages manually by rows and columns

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

Terkadang tidak ada metode splitting di atas yang dapat diterima, atau spreadsheet memiliki format yang tidak mendukung page break maupun Print Area, misalnya CSV berbasis teks. Untuk kasus tersebut GroupDocs.Viewer memungkinkan Anda menentukan secara manual jumlah baris dan/atau kolom yang harus ada pada setiap halaman. Singkatnya, perbedaan antara splitting hanya berdasarkan baris versus splitting berdasarkan baris dan kolom diilustrasikan pada screenshot di bawah.

Jika overload pertama dari metode ForSplitSheetIntoPages digunakan (satu parameter), maka yang diaktifkan adalah splitting hanya berdasarkan baris. Jika overload kedua yang menggunakan dua parameter dipakai, maka splitting berdasarkan baris dan kolom diaktifkan.

Memisahkan worksheet menjadi halaman secara manual berdasarkan baris dan kolom

Adjusting additional options

Semua yang dijelaskan di atas sudah cukup penting untuk merender spreadsheet menggunakan GroupDocs.Viewer. Namun, terdapat banyak opsi tambahan yang tidak wajib, tetapi memungkinkan pengguna menyesuaikan hasil render secara lebih detail.

Beberapa opsi ini direpresentasikan sebagai properti kelas SpreadsheetOptions, yang dapat diakses lewat properti SpreadsheetOptions pada kelas opsi view. Lainnya berada di kelas abstrak ViewOptions yang umum untuk keempat mode render.

Render row and column headings

Ketika MS Excel atau program pengolah tabel serupa membuka dokumen spreadsheet, ia menampilkan heading kolom dan baris; kolom diberi huruf (A, B, C, AA, AB, …) dan baris diberi nomor (1, 2, 3, …, 1048576). Secara default GroupDocs.Viewer tidak menampilkan heading ini, karena mereka merupakan bagian dari antarmuka program pengolah tabel, bukan dokumen itu sendiri. Namun hal ini dapat diubah dengan properti RenderHeadings yang bertipe boolean. Secara default nilai ini false, tetapi bila diaktifkan (true), heading baris dan kolom akan muncul pada dokumen output, seperti pada screenshot di bawah.

Merender heading baris dan kolom

Render worksheet gridlines

Konsep opsi ini mirip dengan yang sebelumnya. Secara default GroupDocs.Viewer tidak menampilkan garis kisi (gridlines) antara sel, karena mereka bukan bagian dari spreadsheet melainkan cara visualisasi tabel oleh program pengolah. Dengan menetapkan properti boolean RenderGridLines ke true, gridlines akan tampil pada dokumen output, seperti pada screenshot berikut.

Merender gridlines worksheet

Control cell text overflow

Seringkali teks dalam sebuah sel tidak muat dalam batas sel tersebut. Bagaimana cara menampilkan teks tersebut? GroupDocs.Viewer menyediakan properti khusus SpreadsheetOptions.TextOverflowMode untuk menangani masalah ini. Properti TextOverflowMode memiliki tipe enum dengan nama yang sama, yakni TextOverflowMode, dan memiliki 4 nilai yang dijelaskan di bawah.

OverlayIfNextIsEmpty

Secara default properti SpreadsheetOptions.TextOverflowMode memiliki nilai OverlayIfNextIsEmpty, yang meniru perilaku default Microsoft Excel. Nilai ini mengizinkan teks meluber ke sel‑sel tetangga, hanya bila sel‑sel tetangga tersebut kosong. Jika sel tetangga tidak kosong, teks yang meluber akan dipotong.

Nilai enum OverlayIfNextIsEmpty

Screenshot di atas menampilkan file HTML yang dirender dari XLSX input dengan nilai OverlayIfNextIsEmpty. Perhatikan sel “B2” — teksnya panjang dan dipotong karena sel “C2” tidak kosong. Sel “C3” juga memiliki teks panjang yang tidak muat, namun meluber ke sel “D2” dan “E2” karena keduanya kosong.

Overlay

Nilai TextOverflowMode.Overlay serupa dengan nilai sebelumnya, namun lebih agresif: teks panjang yang tidak muat dalam batas sel asal selalu meluber, tanpa memperhatikan apakah sel tetangga berisi data atau tidak. Jika sel tetangga memiliki teks atau data, data tersebut akan terhapus.

Nilai enum Overlay

Screenshot di atas memperlihatkan cara kerja ini. Teks panjang pada sel “B2” meluber ke sel “C2”, “D2”, “E2”, “F2”. Akibatnya, teks asli pada sel “C2” dan “F2” terhapus.

HideText

Mode TextOverflowMode.HideText berlawanan dengan mode Overlay — alih‑alih meluber, teks yang tidak muat selalu dipotong, terlepas dari ada tidaknya ruang kosong di sel tetangga.

Nilai enum HideText

Pada screenshot di atas terlihat pada sel “C3” — meskipun ada ruang kosong di sel “D3” dan seterusnya, teks tetap dipotong secara mutlak.

AutoFitColumn

Nilai TextOverflowMode.AutoFitColumn menyelesaikan masalah dengan cara meningkatkan lebar kolom agar muat dengan teks apa pun. Jadi, tidak peduli seberapa panjang teks dalam sel, lebar kolom tempat sel tersebut berada akan diperbesar sehingga seluruh string dapat ditampilkan.

Nilai enum AutoFitColumn

Screenshot di atas menunjukkan cara kerjanya. Tentu saja, pendekatan ini tidak selalu cocok, terutama bila teks dalam sel sangat panjang — dapat membuat halaman menjadi sangat lebar dan menghasilkan gulir horizontal yang tidak nyaman.

Render hidden rows and columns

Microsoft Excel dan program pengolah tabel lainnya memungkinkan menyembunyikan baris atau kolom tertentu. Secara default GroupDocs.Viewer tidak merender baris/kolom tersembunyi tersebut, namun perilaku ini dapat diubah. Properti ViewOptions.SpreadsheetOptions.RenderHiddenRows dan ViewOptions.SpreadsheetOptions.RenderHiddenColumns bila diset ke true akan menampilkan baris dan kolom tersembunyi dalam file output ketika merender spreadsheet ke HTML, PDF, PNG, atau JPEG.

Render hidden worksheets

Seperti baris dan kolom tersembunyi, file spreadsheet dapat berisi satu atau lebih worksheet yang disembunyikan. Secara default GroupDocs.Viewer tidak merender worksheet tersembunyi tersebut. Namun, hal ini dapat diubah dengan properti RenderHiddenPages yang diset ke true. Perlu dicatat bahwa tidak seperti properti yang dijelaskan sebelumnya, RenderHiddenPages berada di kelas abstrak BaseViewOptions, bukan di SpreadsheetOptions.

Skip empty rows and columns

Beberapa spreadsheet bersifat “sparse” — berisi banyak ruang kosong yang dapat memakan banyak ruang. GroupDocs.Viewer memiliki fitur untuk melewatkan baris dan kolom kosong saat merender. Bila fitur ini diaktifkan, baris dan/atau kolom kosong tidak disertakan dalam HTML, PDF, PNG, atau JPEG yang dihasilkan. Properti boolean SpreadsheetOptions.SkipEmptyRows dan SpreadsheetOptions.SkipEmptyColumns mengendalikan fitur ini.

Melewatkan baris dan kolom kosong

Screenshot di atas menunjukkan bahwa kedua opsi SkipEmptyRows dan SkipEmptyColumns diaktifkan.

Render or hide cell comments

Sel dalam dokumen spreadsheet dapat memiliki komentar, dan secara default GroupDocs.Viewer merender semua komentar tersebut. Namun, ini dapat dinonaktifkan dengan properti BaseViewOptions.RemoveComments — bila diset ke true, tidak ada komentar yang akan dirender. Perlu diingat bahwa properti ini berada di kelas BaseViewOptions, bukan di SpreadsheetOptions.

Merender atau menyembunyikan komentar sel

Screenshot di atas menunjukkan rendering file XLSX dengan komentar sel ke format PNG menggunakan opsi default — komentar pada sel “E2” muncul dalam file PNG hasil render.

Set worksheet margins in the output PDF pages

Saat merender worksheet ke format PDF, Anda dapat mengontrol margin halaman — jarak dalam sentimeter dari tepi halaman ke konten. Terdapat 4 properti untuk mengatur margin atas, kanan, bawah, dan kiri:

Secara default keempat properti ini memiliki nilai negatif, yang berarti margin default diterapkan oleh GroupDocs.Viewer. Namun, nilai ini dapat diatur secara eksplisit. Perlu ditekankan bahwa margin halaman hanya berlaku ketika format target adalah PDF.

Potongan kode berikut menunjukkan cara membuat PdfViewOptions, mengatur keempat margin, dan merender dokumen:

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

Gambar berikut memperlihatkan hasilnya:

Menetapkan margin worksheet pada halaman PDF output

Conclusion

Format spreadsheet cukup kompleks, dan dokumen dapat memiliki konten yang sangat beragam dalam hal tipe dan panjang. Dalam banyak kasus tidak mungkin merender dokumen spreadsheet yang kompleks ke format tertentu dengan opsi default, itulah mengapa GroupDocs.Viewer menyediakan rangkaian properti yang sangat lengkap; dengan properti‑properti tersebut setiap pengguna dapat menyesuaikan proses render sesuai kebutuhan masing‑masing.

See Also

Get a free trial

Anda dapat mengunduh versi trial gratis GroupDocs.Viewer untuk .NET di releases.groupdocs.com. Anda juga dapat memperoleh lisensi sementara untuk mencoba semua fitur dan fungsionalitas tanpa batasan dari di sini.