Gambaran Umum

Spreadsheet documents adalah dokumen yang berisi data dalam bentuk tabel — di dalam baris dan kolom. Mereka juga dikenal sebagai workbooks. Ada 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 sebagainya. Semua itu membentuk apa yang disebut keluarga format Spreadsheet. GroupDocs.Viewer mendukung hampir semua format spreadsheet saat 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 harus menggunakannya.

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

Penggunaan Dasar

Pertama-tama kita perlu membicarakan tentang opsi. Ada kelas terpisah dalam API publik: SpreadsheetOptions di dalam GroupDocs.Viewer.Options. Kelas ini dirancang khusus untuk menyesuaikan rendering keluarga format Spreadsheet. Kelas ini dapat diakses untuk keempat opsi tampilan melalui properti SpreadsheetOptions :

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

Secara singkat, 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 mendemonstrasikan rendering 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 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 pemrosesan tabel seperti Microsoft Excel, worksheet direpresentasikan sebagai tab. Beberapa format spreadsheet mungkin hanya memiliki satu worksheet; 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 didukung yang memiliki halaman, tetapi dalam konteks keluarga format Spreadsheet ia menggambarkan nomor worksheet yang akan dilihat.

Harap dicatat bahwa penomoran halaman secara umum dan penomoran worksheet secara khusus menggunakan basis 1, bukan 0, sehingga dimulai dari “1”, bukan dari “0”.

Contoh di bawah 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);
}

Membagi lembar kerja menjadi halaman

GroupDocs.Viewer merender dokumen ke halaman, di mana sebuah halaman dipahami sebagai area persegi panjang berukuran relatif kecil, sebanding dengan area tampilan atau kertas A4. Di sisi lain, worksheet dapat sangat besar. Khususnya, format XLS yang kini usang mendukung maksimum 256 kolom dan 65536 baris, sementara format XLSX (Office Open XML Workbook) yang lebih baru dan Microsoft Excel keduanya mendukung hingga 16384 kolom dan 1048576 baris. “Menyesuaikan” worksheet ke halaman merupakan bagian penting dalam merender spreadsheet dengan GroupDocs.Viewer. Untuk menyesuaikan worksheet ke halaman, GroupDocs.Viewer melakukan worksheet splitting — worksheet dibagi menjadi beberapa potongan persegi panjang, dan masing‑masing ditempatkan pada halaman terpisah. Ada 5 metode berbeda, yang tercantum dan dijelaskan di bawah.

Yang penting — semua metode pemisahan ini ditentukan dengan cara yang sama — menggunakan metode statis tertentu (factory method) yang membuat instance kelas SpreadsheetOptions.

Render seluruh lembar kerja pada satu halaman

SpreadsheetOptions.ForOnePagePerSheet()

Cara paling mudah dan sederhana — mematikan pemisahan dan menyesuaikan ukuran halaman agar muat semua konten seluruh worksheet. Ini merupakan pilihan yang baik ketika sudah diketahui bahwa worksheet berukuran kecil. Namun, jika worksheet sangat besar, pendekatan ini dapat menghasilkan hasil yang buruk. Khususnya, saat merender ke format HTML, dokumen HTML yang dihasilkan dapat menjadi sangat besar, puluhan atau bahkan ratusan MiB, yang dapat menimbulkan masalah saat melihat file besar tersebut di peramban web. Saat merender ke format JPEG, keadaan dapat menjadi lebih buruk jika lebar atau tinggi melebihi batas maksimum 65535 piksel. Jadi gunakan mode ini dengan pertimbangan.

Render worksheet on one page

Membagi lembar kerja berdasarkan pemisah halaman

SpreadsheetOptions.ForRenderingByPageBreaks()

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

Dengan metode ini GroupDocs.Viewer mengikuti Microsoft Excel dan membagi worksheet sesuai pemisah halaman, seperti yang dilakukan Microsoft Excel.

Perlu disebutkan bahwa opsi ini — membagi worksheet berdasarkan pemisah halaman — merupakan opsi default dari properti BaseViewOptions.SpreadsheetOptions, sehingga ketika Anda membuat instance kelas opsi tampilan, opsi “ForRenderingByPageBreaks()” dipilih secara default.

Render hanya area cetak

SpreadsheetOptions.ForRenderingPrintArea()

Selain pemisah halaman, Microsoft Excel memiliki konsep “Print Area”. Print Area sebenarnya adalah satu atau lebih rentang sel dalam worksheet yang ditetapkan untuk pencetakan, 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 item “Set Print Area” (lihat tangkapan layar di bawah). Untuk menambahkan rentang sel lain ke Print Area, pilih rentang baru tersebut, klik tombol “Print Area”, lalu pilih item “Add to Print Area”. Pada mode “Page Break Preview” Anda dapat melihat semua rentang sel dalam Print Area.

Render only print area

Render area cetak dan bagi berdasarkan pemisah halaman

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer memiliki fitur unik — menggabungkan Print Area dan pemisah halaman dalam satu mode. Dalam kasus ini GroupDocs.Viewer memperhitungkan semua rentang sel dari Print Area serta pemisah halaman dalam worksheet dan menerapkannya secara bersamaan untuk membagi worksheet ke halaman.

Pada tangkapan layar berikut garis merah menunjukkan Print Area, dan garis biru menunjukkan pemisah halaman.

Render print area and split by page breaks

Membagi lembar kerja menjadi halaman secara manual berdasarkan baris dan kolom

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

Kadang tidak ada metode pemisahan yang dijelaskan di atas yang dapat diterima, atau spreadsheet memiliki format yang tidak mendukung pemisah halaman dan Print Area, misalnya CSV berbasis teks. Untuk kasus tersebut GroupDocs.Viewer memungkinkan Anda secara manual menentukan jumlah baris dan/atau kolom yang harus ada pada setiap halaman. Singkatnya, perbedaan antara pemisahan hanya berdasarkan baris vs. pemisahan berdasarkan baris dan kolom diilustrasikan pada tangkapan layar di bawah.

Jika overload pertama dari metode ForSplitSheetIntoPages digunakan, dengan satu parameter, maka pemisahan hanya berdasarkan baris diaktifkan. Jika overload kedua digunakan, dengan dua parameter, maka pemisahan berdasarkan baris dan kolom diaktifkan.

Split worksheet into pages manually by rows and columns

Menyesuaikan opsi tambahan

Semua yang dijelaskan di atas merupakan hal esensial dan cukup untuk merender spreadsheet menggunakan GroupDocs.Viewer. Namun, terdapat banyak opsi tambahan, yang tidak wajib, tetapi memungkinkan pengguna menyesuaikan hasil rendering lebih lanjut.

Beberapa opsi ini direpresentasikan sebagai properti dari kelas SpreadsheetOptions, yang dapat diakses sebagai properti SpreadsheetOptions dari kelas opsi tampilan. Opsi lainnya terletak di kelas abstrak ViewOptions yang umum untuk keempat mode rendering.

Render judul baris dan kolom

Saat MS Excel atau program pemrosesan tabel serupa membuka dokumen spreadsheet, ia menampilkan judul kolom dan baris, kolom diberi huruf (A, B, C, AA, AB, …) dan baris diberi nomor (1, 2, 3, …, 1048576). Saat merender, GroupDocs.Viewer secara default tidak menampilkan judul ini, karena mereka merupakan bagian dari antarmuka pemroses tabel, bukan dokumen itu sendiri. Namun hal ini dapat diubah dengan properti RenderHeadings yang bertipe boolean. Secara default properti ini dinonaktifkan dengan nilai false, tetapi ketika diaktifkan (true), judul baris dan kolom akan muncul dalam dokumen output, seperti yang terlihat pada tangkapan layar di bawah.

Render row and column headings

Render garis kisi lembar kerja

Konsep opsi ini sangat mirip dengan yang sebelumnya. Secara default GroupDocs.Viewer tidak menampilkan garis kisi di antara sel, karena mereka bukan bagian dari spreadsheet, melainkan cara merepresentasikan konten tabel pada pemroses tabel tertentu. Namun, dengan menggunakan properti RenderGridLines yang bertipe boolean, Anda dapat meniru perilaku MS Excel. Tetapkan nilai true pada properti SpreadsheetOptions.RenderGridLines, dan garis kisi akan muncul dalam dokumen output, seperti yang ditunjukkan pada tangkapan layar di bawah.

Render worksheet gridlines

Kontrol overflow teks sel

Ini adalah skenario yang cukup umum, ketika teks dalam sebuah sel tidak muat dalam batas sel tersebut. Bagaimana menampilkan teks ini dengan tepat? GroupDocs.Viewer menyediakan properti khusus SpreadsheetOptions.TextOverflowMode untuk menyelesaikan masalah ini. Properti TextOverflowMode memiliki nilai bertipe dengan nama yang sama, TextOverflowMode, dan merupakan tipe enum dengan 4 item yang dijelaskan di bawah.

OverlayIfNextIsEmpty

Secara default properti SpreadsheetOptions.TextOverflowMode memiliki nilai OverlayIfNextIsEmpty, yang meniru perilaku default Microsoft Excel. Singkatnya, nilai ini memungkinkan teks meluber ke sel bersebelahan, tetapi hanya jika sel‑sel tersebut tidak berisi data. Jika sel bersebelahan tidak kosong, teks yang meluber akan dipotong.

OverlayIfNextIsEmpty enum value

Tangkapan layar di atas menunjukkan 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, tetapi meluber ke sel “D2” dan “E2” karena keduanya kosong.

Overlay

Nilai TextOverflowMode.Overlay sedikit mirip dengan yang sebelumnya, tetapi dapat dianggap lebih agresif: teks panjang yang tidak muat dalam batas sel asli selalu meluber, terlepas dari isi sel‑sel bersebelahan. Jika sel‑sel bersebelahan juga berisi teks atau data lain, data tersebut akan dihapus.

Overlay enum value

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

HideText

Mode TextOverflowMode.HideText berfungsi berlawanan dengan mode Overlay yang dijelaskan sebelumnya — alih‑alih meluber, teks yang tidak muat dalam batas selnya akan dipotong secara mutlak, terlepas apakah ada ruang kosong di sel‑sel bersebelahan atau tidak.

HideText enum value

Pada tangkapan layar di atas hal ini terlihat pada sel “C3” — meskipun ada ruang kosong di sel “D3” dan seterusnya, teks tetap dipotong tanpa syarat.

AutoFitColumn

Nilai TextOverflowMode.AutoFitColumn menyelesaikan masalah dengan pendekatan lain — memperlebar lebar kolom agar muat teks pada sel mana pun. Jadi, tidak peduli seberapa panjang teks dalam sel tertentu, lebar kolom tempat sel tersebut berada akan diperlebar agar seluruh string muat.

AutoFitColumn enum value

Tangkapan layar di atas menunjukkan cara kerjanya. Tentu saja, pendekatan ini mungkin tidak cocok dalam beberapa kasus, terutama ketika teks dalam sel sangat panjang — hal ini dapat membuat halaman menjadi sangat lebar dengan gulir horizontal yang mengganggu.

Render baris dan kolom tersembunyi

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

Render lembar kerja tersembunyi

Seperti baris dan kolom tersembunyi yang dijelaskan di atas, file spreadsheet dapat berisi satu atau lebih worksheet tersembunyi. Dan seperti kasus sebelumnya, secara default GroupDocs.Viewer tidak merender worksheet tersembunyi. Namun hal ini dapat diubah menggunakan properti RenderHiddenPages dengan menyetel nilainya menjadi true. Perlu disebutkan bahwa tidak seperti properti yang dijelaskan sebelumnya, RenderHiddenPages terletak bukan di SpreadsheetOptions, melainkan di kelas abstrak BaseViewOptions yang umum untuk semua opsi tampilan.

Lewati baris dan kolom kosong

Beberapa spreadsheet bersifat “sparse” — mereka mengandung banyak ruang kosong yang dapat memakan banyak ruang. GroupDocs.Viewer memiliki fitur untuk melewatkan baris dan kolom kosong dari proses rendering. Jika fitur ini diaktifkan, baris dan/atau kolom kosong dikeluarkan dari HTML, PDF, PNG, dan JPEG yang dihasilkan. Properti boolean SpreadsheetOptions.SkipEmptyRows dan SpreadsheetOptions.SkipEmptyColumns bertanggung jawab atas fitur ini.

Skip empty rows and columns

Tangkapan layar di atas memperlihatkan bahwa baik SkipEmptyRows maupun SkipEmptyColumns diaktifkan.

Render atau sembunyikan komentar sel

Sel dalam dokumen spreadsheet dapat memiliki komentar, dan secara default GroupDocs.Viewer merender semuanya. Namun hal ini dapat dinonaktifkan menggunakan properti BaseViewOptions.RemoveComments — jika nilai properti ini diset ke true, tidak ada komentar yang akan dirender. Perlu dicatat bahwa properti ini berada di kelas BaseViewOptions, bukan di SpreadsheetOptions.

Render or hide cell comments

Tangkapan layar di atas memperlihatkan rendering file XLSX dengan komentar sel ke format PNG menggunakan opsi default — komentar untuk sel “E2” muncul dalam file PNG yang dihasilkan.

Atur margin lembar kerja pada halaman PDF output

Saat merender worksheet ke format PDF, dimungkinkan mengontrol margin halaman — jarak dalam sentimeter dari tepi halaman ke konten. Ada 4 properti untuk mengontrol 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 diterapkan ketika format target adalah PDF.

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:

Set worksheet margins in the output PDF pages

Kesimpulan

Format spreadsheet cukup kompleks, dan dokumen dapat memiliki konten yang sangat beragam baik dari segi tipe maupun panjang. Dalam banyak kasus tidak mungkin merender dokumen spreadsheet yang kompleks ke format tertentu dengan opsi default, dan itulah mengapa GroupDocs.Viewer menyediakan rangkaian properti yang komprehensif; dengan properti‑properti tersebut setiap pengguna dapat menyesuaikan rendering agar sesuai dengan kebutuhannya.

Lihat Juga

Dapatkan percobaan gratis

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