GroupDocs.Viewer for .NET'te Elektronik Tablolarla Çalışma

Genel Bakış

Spreadsheet belgeleri satır ve sütunlar içinde tablo biçiminde veri içeren belgelerdir. Aynı zamanda çalışma kitapları olarak da bilinirler. Çeşitli spreadsheet belge formatları vardır — Office Open XML (XLSX, XLSM vb.), Microsoft Excel Binary File Format (XLS, XLT), OpenDocument Spreadsheet formatı (ODS, FODS, OTS), metin tabanlı ayırıcı‑tabanlı formatlar (CSV, TSV vb.) ve benzerleri. Tüm bunlar sözde Spreadsheet formatları ailesini oluşturur. GroupDocs.Viewer, neredeyse tüm spreadsheet formatlarını içe aktarabilir ve bunları HTML, PDF, PNG ve JPEG’ye dönüştürmeye (render) izin verir. Bu makalede bunun nasıl yapılacağı, hangi seçeneklerin mevcut olduğu ve ne zaman‑neden kullanılacağı açıklanmıştır.

MS Excel’de açılmış bir çalışma kitabının HTML formatına render edilmesi

Temel kullanım

Öncelikle seçeneklerden bahsetmemiz gerekir. Genel bir API içinde ayrı bir sınıf vardır: SpreadsheetOptions – GroupDocs.Viewer.Options içinde. Bu sınıf, Spreadsheet formatları ailesinin render edilmesini ayarlamak için özel olarak tasarlanmıştır. Dört görüntüleme seçeneğinin tamamında SpreadsheetOptions özelliği üzerinden erişilebilir:

HtmlViewOptions.SpreadsheetOptions – bir Spreadsheet belgesini HTML’ye render ederken,
PdfViewOptions.SpreadsheetOptions – bir Spreadsheet belgesini PDF’ye render ederken,
PngViewOptions.SpreadsheetOptions – bir Spreadsheet belgesini PNG’ye render ederken,
JpgViewOptions.SpreadsheetOptions – bir Spreadsheet belgesini JPEG’ye render ederken.

Açıkça belirtilmediğinde, SpreadsheetOptions özelliği, bu makalenin ilerleyen bölümlerinde açıklanacak olan, SpreadsheetOptions sınıf örneğinin varsayılan örtük değerine sahiptir.

Bir bakışta, GroupDocs.Viewer ile bir Spreadsheet belgesinin render edilmesi son derece kolaydır ve diğer tüm formatlarla aynıdır — bir ViewOptions örneği oluşturun, belirtilen giriş Spreadsheet belgesiyle bir Viewer nesnesi oluşturun ve Viewer.View(viewOptions) metodunu çağırın. Aşağıdaki kod örneği, tek bir giriş Spreadsheet dosyasını 4 çıktı formatına (HTML, PDF, PNG ve JPEG) render etmeyi gösterir. Lütfen seçenek sınıflarının örneklerini oluşturmanın dışındaki herhangi bir spreadsheet‑özel ayarın bulunmadığını, yani tüm spreadsheet seçeneklerinin varsayılan değerlerde olduğunu unutmayın.

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

Şimdi çalışma sayfalarından (worksheets) bahsedelim. Her spreadsheet en az bir çalışma sayfasına sahiptir. Microsoft Excel gibi çoğu tablo işleme yazılımında çalışma sayfaları sekme olarak gösterilir. Bazı spreadsheet formatları yalnızca tek bir çalışma sayfasına sahip olabilir; buna örnek olarak tüm metin‑tabanlı ayırıcı‑delimited formatlar (CSV, TSV vb.) verilebilir.

Varsayılan olarak GroupDocs.Viewer, verilen spreadsheet içinde bulunan tüm çalışma sayfalarını render eder. Ancak bu davranış değiştirilebilir. Viewer.View() metodunun bir 2. parametresi vardır — Int32[] pageNumbers. Bu parametre kullanıldığında yalnızca belirtilen sayfalar (çalışma sayfaları) render edilir. Bu parametre evrenseldir ve sayfalara sahip tüm desteklenen formatlara uygulanır; Spreadsheet formatları ailesi bağlamında ise tam olarak görüntülenecek çalışma sayfası numaralarını tanımlar.

Sayfa numaralandırmasının (ve dolayısıyla çalışma sayfası numaralandırmasının) 1‑tabanlı, 0‑tabanlı olmadığını, yani “1”den başladığını unutmayın.

Aşağıdaki örnek, 3 çalışma sayfası bulunan bir spreadsheet’te 1. ve 3. çalışma sayfasını PNG olarak render etmeyi gösterir.

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

Çalışma sayfalarını sayfalara bölme

GroupDocs.Viewer belgeleri, bir sayfa olarak adlandırdığımız, ekran veya A4 kağıdına benzer boyutta, dikdörtgen bir alana render eder. Öte yandan, çalışma sayfaları çok büyük olabilir. Özellikle artık kullanılmayan XLS formatı maksimum 256 sütun ve 65 536 satır desteklerken, yeni XLSX (Office Open XML Workbook) formatı ve Microsoft Excel 16384 sütun ve 1 048 576 satıra kadar çıkabilir. Çalışma sayfalarını sayfalara “sığdırmak”, GroupDocs.Viewer ile spreadsheet render etmenin kritik bir parçasıdır. Bir çalışma sayfasını sayfa(lar)a sığdırmak için GroupDocs.Viewer bir çalışma sayfası bölme işlemi gerçekleştirir — çalışma sayfası birden çok dikdörtgen parçaya bölünür ve her biri ayrı bir sayfaya yerleştirilir. Aşağıda beş farklı yöntem listelenmiş ve açıklanmıştır.

Önemli nokta — bu bölme yöntemlerinin tümü aynı şekilde belirtilir: SpreadsheetOptions sınıfının bir örneğini oluşturan özel statik (factory) metot kullanılarak.

Tüm çalışma sayfasını tek bir sayfada göster

SpreadsheetOptions.ForOnePagePerSheet()

En kolay ve en basit yol — bölmeyi kapatıp sayfa boyutunu, tüm çalışma sayfasının içeriğini sığdıracak şekilde ayarlamak. Çalışma sayfasının zaten küçük olduğu biliniyorsa bu iyi bir tercihtir. Ancak çalışma sayfası gerçekten büyükse, bu yöntem korkunç sonuçlar doğurabilir. Özellikle HTML formatına render edildiğinde, ortaya çıkan HTML belgesi onlarca hatta yüzlerce MiB boyutunda olabilir ve bu durum web tarayıcılarında görüntülenmesini zorlaştırır. JPEG’e render edildiğinde ise genişlik ya da yükseklik 65 535 piksel sınırını aşarsa durum daha da kötüye gider. Bu modu bilinçli olarak kullanın.

Çalışma sayfasını tek bir sayfada render etme

Sayfa sonlarına (page breaks) göre böl

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel, kağıt boyutu ve sayfa ayarları (yönlendirme, kenar boşlukları vb.) temelinde otomatik sayfa sonları ekler. “View” sekmesinde “Page Break Preview” moduna geçerseniz, çalışma sayfasının tüm alanını dikdörtgen parçalara bölen mavi hatları görürsünüz; her bir parça “Page 1”, “Page 2” gibi etiketlenir. Bu, Microsoft Excel’in bir çalışma sayfasını sayfalara bölme önerisidir.

Bu yöntemde GroupDocs.Viewer, Microsoft Excel’in yaptığı gibi sayfa sonlarına göre bölme işlemini gerçekleştirir.

Bu seçenek — “sayfa sonlarına göre bölme” — varsayılan olarak BaseViewOptions.SpreadsheetOptions özelliğinde bulunur; yani bir view options sınıfı örneği oluşturduğunuzda, [ForRenderingByPageBreaks()] seçeneği otomatik olarak seçilir.

Yalnızca yazdırma alanını (print area) render et

SpreadsheetOptions.ForRenderingPrintArea()

Microsoft Excel’de, sayfa sonlarına ek olarak “Print Area” (Yazdırma Alanı) kavramı vardır. Yazdırma Alanı, bir çalışma sayfasındaki bir veya daha fazla hücre aralığını ifade eder; yalnızca bu alandaki içerik yazdırılır, dışındaki içerik tamamen yok sayılır. Bir hücre aralığını Yazdırma Alanı’na eklemek için “Page Layout” sekmesine gidin, “Print Area” düğmesine tıklayın ve “Set Print Area” öğesini seçin (aşağıdaki ekran görüntüsüne bakın). Başka bir aralığı eklemek isterseniz, yeni aralığı seçip yine “Print Area” → “Add to Print Area” adımını izleyin. “Page Break Preview” modunda Yazdırma Alanındaki tüm hücre aralıklarını görebilirsiniz.

Yazdırma alanını render et ve sayfa sonlarına göre böl

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer, benzersiz bir özellik sayesinde Yazdırma Alanı ve sayfa sonlarını tek bir modda birleştirir. Bu durumda Viewer, hem Yazdırma Alanı’nın tüm hücre aralıklarını hem de sayfa sonlarını dikkate alarak çalışma sayfasını aynı anda bölür.

Aşağıdaki ekran görüntüsünde kırmızı çizgi Yazdırma Alanını, mavi çizgi ise sayfa sonlarını göstermektedir.

Yazdırma alanını render et ve sayfa sonlarına göre böl

Çalışma sayfasını satır ve sütun bazlı manuel olarak böl

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

Yukarıdaki bölme yöntemlerinden hiçbiri uygun olmadığında ya da spreadsheet formatı (ör. metin‑tabanlı CSV) sayfa sonları ve Yazdırma Alanını desteklemediğinde bu yöntem kullanılabilir. Kullanıcı, her sayfada bulunması gereken satır ve/veya sütun sayısını manuel olarak belirtebilir. Aşağıdaki ekran görüntüsü, yalnızca satır bazlı bölme ile satır‑ve‑sütun bazlı bölme arasındaki farkı gösterir.

Eğer ForSplitSheetIntoPages metodunun ilk aşırı yüklemesi (tek parametre) kullanılırsa, yalnızca satır bazlı bölme etkinleşir. İkinci aşırı yükleme (iki parametre) kullanıldığında ise satır‑ve‑sütun bazlı bölme etkinleşir.

Çalışma sayfasını satır ve sütun bazlı manuel olarak böl

Ek seçeneklerin ayarlanması

Yukarıda açıklananlar, GroupDocs.Viewer ile spreadsheet’leri render etmek için temel ve yeterli bileşenlerdir. Bununla birlikte, zorunlu olmayan ancak sonuçları daha da özelleştirmeye yarayan bir dizi ek seçenek de mevcuttur.

Bu seçeneklerden bazıları, SpreadsheetOptions sınıfının özellikleri olarak bulunur ve aynı sınıf, view options sınıflarının bir SpreadsheetOptions özelliği aracılığıyla erişilebilir. Diğerleri ise tüm 4 renderleme modunda ortak olan, soyut ViewOptions sınıfında yer alır.

Satır ve sütun başlıklarını render et

MS Excel veya benzeri bir tablo işleme programı bir spreadsheet belgesi açtığında, sütun ve satır başlıklarını gösterir; sütunlar harf (A, B, C, AA, AB, …) ile, satırlar ise sayı (1, 2, 3, …, 1048576) ile etiketlenir. Varsayılan olarak GroupDocs.Viewer bu başlıkları göstermez, çünkü bunlar belge içeriklerinden ziyade tablo işlemcisinin arayüz parçasıdır. Ancak bu davranış, RenderHeadings (bool) özelliği ile değiştirilebilir. Varsayılan değeri false’tır; true yapıldığında satır ve sütun başlıkları çıktı belgesinde yer alır (aşağıdaki ekran görüntüsünde görülebilir).

Çalışma sayfası grid (ızgara) çizgilerini render et

Bu seçenek, bir öncekiyle çok benzer bir mantığa sahiptir. Varsayılan olarak GroupDocs.Viewer, hücreler arasındaki ızgara çizgilerini göstermez; çünkü bunlar da spreadsheet’in bir parçası değil, ilgili tablo işlemcisinin bir gösterim şeklidir. RenderGridLines (bool) özelliği true olarak ayarlandığında, MS Excel davranışı taklit edilir ve ızgara çizgileri çıktı belgesine eklenir (aşağıdaki ekran görüntüsünde gösterildiği gibi).

Çalışma sayfası ızgara çizgilerini render et

Hücre metni taşmasını kontrol et

Bazı durumlarda hücre içindeki metin, hücrenin sınırlarına sığmaz. Bu problemi çözmek için GroupDocs.Viewer, SpreadsheetOptions.TextOverflowMode adlı özel bir özellik sunar. TextOverflowMode enum’ı dört olası değere sahiptir; aşağıda açıklanmıştır.

OverlayIfNextIsEmpty

Varsayılan değer OverlayIfNextIsEmpty’dir ve MS Excel’in standart davranışını taklit eder. Metin, yanındaki hücre boş ise komşu hücrelere taşabilir; yan hücrede veri varsa taşma kesilir.

Örnekte, B2 hücresi uzun bir metin içeriyor ve C2 hücresi dolu olduğu için metin kesiliyor. C3 hücresi ise uzun bir metne sahip; D2 ve E2 hücreleri boş olduğu için metin bu hücrelere taşabiliyor.

Overlay

Overlay değeri, öncekiyle benzer fakat daha agresiftir: Metin, komşu hücrelerin dolu olup olmamasına bakılmaksızın her zaman taşar ve yan hücrelerdeki mevcut veri silinir.

Örnekte, B2 hücresindeki uzun metin C2, D2, E2, F2 hücrelerine taşmış; sonuçta C2 ve F2 hücrelerindeki eski veriler silinmiştir.

HideText

HideText modu, Overlay’ın tam tersidir: Metin, kendi hücresinin sınırlarını aştığında, yan hücrede boş yer olsa dahi kesilir ve hiç taşmaz.

Görüntüde, C3 hücresindeki metin, D3 hücresi boş olsa bile kesilmiştir.

AutoFitColumn

AutoFitColumn değeri, metni sığdırmak için ilgili sütunun genişliğini artırır. Metin ne kadar uzun olursa olsun, bulunduğu sütun genişletilerek tüm metin gösterilir.

Bu yaklaşım bazı durumlarda uygun olmayabilir; çok uzun metinler sayfanın aşırı genişlemesine ve yatay kaydırma çubuklarının ortaya çıkmasına neden olabilir.

Gizli satır ve sütunları render et

Microsoft Excel ve diğer tablo işlemcileri belirli satır ve sütunları gizleme imkanı sunar. Varsayılan olarak GroupDocs.Viewer bu gizli satır ve sütunları render etmez; ancak bu davranış ViewOptions.SpreadsheetOptions.RenderHiddenRows ve ViewOptions.SpreadsheetOptions.RenderHiddenColumns (bool) özellikleri true yapılırsa değiştirilebilir. Böylece HTML, PDF, PNG ya da JPEG formatında çıktı alınırken gizli satır ve sütunlar da gösterilir.

Gizli çalışma sayfalarını render et

Yukarıda anlatılan gizli satır/sütun gibi, bir spreadsheet dosyası bir veya birden fazla gizli çalışma sayfası içerebilir. Varsayılan olarak bu gizli sayfalar gösterilmez; ancak RenderHiddenPages (bool) özelliği true yapılırsa, gizli çalışma sayfaları da render edilir. Bu özellik SpreadsheetOptions içinde değil, tüm view options sınıflarının ortak üst sınıfı BaseViewOptions içinde yer alır.

Boş satır ve sütunları atla

Bazı spreadsheet’ler “seyrek” (sparse) olup çok sayıda boş hücre barındırabilir; bu durum çıktı dosyasının boyutunu arttırabilir. GroupDocs.Viewer, boş satır ve sütunları atlama özelliğine sahiptir. Bu özellik etkinleştirildiğinde, boş satır ve/veya sütunlar çıktı HTML, PDF, PNG ve JPEG’den çıkarılır. Kontrol eden boolean özellikler:

SpreadsheetOptions.SkipEmptyRows
SpreadsheetOptions.SkipEmptyColumns

Ekran görüntüsünde hem SkipEmptyRows hem de SkipEmptyColumns özelliklerinin aktif olduğu görülüyor.

Hücre yorumlarını render et ya da gizle

Spreadsheet belgelerinde hücre yorumları bulunabilir; varsayılan olarak GroupDocs.Viewer bu yorumları render eder. Yorumları gizlemek için BaseViewOptions.RemoveComments (bool) özelliği true olarak ayarlanır; bu durumda hiçbir yorum gösterilmez. Bu özellik BaseViewOptions sınıfında bulunur, SpreadsheetOptions içinde değildir.

Ekran görüntüsü, varsayılan ayarlarla XLSX dosyasının hücre yorumlarıyla PNG’ye render edildiğini gösterir; “E2” hücresindeki yorum çıktı PNG’de yer alıyor.

Çıktı PDF sayfalarında çalışma sayfası kenar boşluklarını ayarla

Çalışma sayfalarını PDF formatına render ederken, sayfa kenar boşluklarını (sayfa kenarından içeriğe centimetre cinsinden mesafe) kontrol edebilirsiniz. Üst, sağ, alt ve sol kenar boşluklarını ayarlayan dört özellik şunlardır:

SpreadsheetOptions.TopMargin
SpreadsheetOptions.RightMargin
SpreadsheetOptions.BottomMargin
SpreadsheetOptions.LeftMargin

Varsayılan olarak bu dört özellik de negatif değer taşır; bu, GroupDocs.Viewer’ın varsayılan kenar boşluklarını kullandığı anlamına gelir. Değerler açıkça ayarlanabilir; ancak kenar boşlukları yalnızca hedef format PDF olduğunda uygulanır.

Aşağıdaki kod örneği, PdfViewOptions oluşturup tüm dört kenar boşluğunu ayarlayarak bir belgeyi render etmeyi gösterir:

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

Sonucun görseli:

Çıktı PDF sayfalarında çalışma sayfası kenar boşlukları

Sonuç

Spreadsheet formatları oldukça karmaşıktır ve belgeler, değişken tip ve uzunlukta çok farklı içeriklere sahip olabilir. Çoğu durumda, varsayılan seçeneklerle karmaşık bir spreadsheet belgesini istenen bir formata render etmek mümkün olmaz; bu yüzden GroupDocs.Viewer, kullanıcıların render sonuçlarını kendi ihtiyaçlarına göre ayarlamasını sağlayan kapsamlı bir özellik seti sunar.

İlgili Bağlantılar

Ücretsiz deneme alın

GroupDocs.Viewer for .NET’in ücretsiz deneme sürümünü releases.groupdocs.com adresinden indirebilirsiniz. Ayrıca tüm özellikleri ve işlevleri kısıtlama olmadan denemeniz için geçici lisansı buradan alabilirsiniz.

Genel Bakış#

Temel kullanım#

Çalışma sayfalarını sayfalara bölme#

Tüm çalışma sayfasını tek bir sayfada göster#

Sayfa sonlarına (page breaks) göre böl#

Yalnızca yazdırma alanını (print area) render et#

Yazdırma alanını render et ve sayfa sonlarına göre böl#

Çalışma sayfasını satır ve sütun bazlı manuel olarak böl#

Ek seçeneklerin ayarlanması#

Satır ve sütun başlıklarını render et#

Çalışma sayfası grid (ızgara) çizgilerini render et#

Hücre metni taşmasını kontrol et#

OverlayIfNextIsEmpty#

Overlay#

HideText#

AutoFitColumn#

Gizli satır ve sütunları render et#

Gizli çalışma sayfalarını render et#

Boş satır ve sütunları atla#

Hücre yorumlarını render et ya da gizle#

Çıktı PDF sayfalarında çalışma sayfası kenar boşluklarını ayarla#

Sonuç#

İlgili Bağlantılar#

Ücretsiz deneme alın#