مرور کلی

اسناد صفحه‌گسترده اسنادی هستند که داده‌ها را به صورت جدول — در ردیف‌ها و ستون‌ها — دارند. این اسناد همچنین به‌عنوان workbooks شناخته می‌شوند. فرمت‌های متعددی برای اسناد صفحه‌گسترده وجود دارد — Office Open XML (مانند XLSX، XLSM و غیره)، Microsoft Excel Binary File Format (XLS، XLT)، فرمت OpenDocument Spreadsheet (ODS، FODS، OTS)، فرمت‌های مبتنی بر متن با جداکننده (مانند CSV، TSV و غیره) و غیره. همهٔ این‌ها خانواده‌ای به نام Spreadsheet formats family را تشکیل می‌دهند. GroupDocs.Viewer تقریباً همهٔ فرمت‌های صفحه‌گسترده را در زمان وارد شدن پشتیبانی می‌کند و امکان رندر (تبدیل) آن‌ها به HTML، PDF، PNG و JPEG را فراهم می‌سازد. این مقاله نحوهٔ انجام این کار، گزینه‌های موجود و زمان و دلیل استفاده از هر یک را توضیح می‌دهد.

Render یک workbook، باز شده در MS Excel، به فرمت HTML

استفادهٔ پایه‌ای

ابتدا باید دربارهٔ گزینه‌ها صحبت کنیم. یک کلاس جداگانه در API عمومی وجود دارد: SpreadsheetOptions در فضای نام GroupDocs.Viewer.Options. این کلاس به‌طور خاص برای تنظیم رندر خانوادهٔ فرمت‌های صفحه‌گسترده طراحی شده است. این کلاس از طریق ویژگی SpreadsheetOptions برای چهار گزینهٔ نمایش در دسترس است:

اگر صراحتاً مقداردهی نشود، ویژگی SpreadsheetOptions به‌صورت پیش‌فرض یک نمونهٔ ضمنی از کلاس SpreadsheetOptions را در خود دارد که بعداً در این مقاله توضیح داده می‌شود.

به‌طور کلی، رندر یک سند Spreadsheet با GroupDocs.Viewer بسیار ساده و مشابه سایر فرمت‌ها است — یک نمونهٔ ViewOptions ایجاد کنید، یک نمونهٔ Viewer با سند ورودی موردنظر بسازید و متد Viewer.View(viewOptions) را صدا بزنید. نمونهٔ کد زیر رندر یک فایل Spreadsheet ورودی را به چهار فرمت خروجی HTML، PDF، PNG و JPEG نشان می‌دهد. توجه داشته باشید به‌جز ساخت نمونه‌های کلاس‌های گزینه، تنظیم خاصی برای صفحه‌گسترده‌ها انجام نشده است؛ تمام گزینه‌های صفحه‌گسترده به مقادیر پیش‌فرض اعمال می‌شوند.

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

حالا دربارهٔ worksheets (ورق‌ها) صحبت می‌کنیم. هر صفحه‌گسترده حداقل یک worksheet دارد. در اکثر نرم‌افزارهای پردازش جدول مانند Microsoft Excel، worksheet‌ها به‌صورت تب‌ها نمایش داده می‌شوند. برخی فرمت‌های صفحه‌گسترده ممکن است تنها یک worksheet داشته باشند؛ این شامل تمام فرمت‌های مبتنی بر متن با جداکننده (مانند CSV، TSV و غیره) می‌شود.

به‌صورت پیش‌فرض GroupDocs.Viewer همهٔ worksheet‌ها را داخل spreadsheet داده‌شده رندر می‌کند؛ اما می‌توان این رفتار را تغییر داد. متد Viewer.View() یک overload دارد که به‌عنوان پارامتر دوم یک مجموعه از شماره‌های صفحات (Int32[] pageNumbers) می‌گیرد. وقتی این پارامتر استفاده شود، تنها صفحات (در زمینهٔ Spreadsheet، شمارهٔ worksheet‌ها) مشخص‌شده رندر می‌شوند.

لطفاً توجه داشته باشید شماره‌گذاری صفحات به‌صورت ۱‑پایه (نه ۰‑پایه) است، به این معنی که از «۱» شروع می‌شود، نه از «۰».

مثال زیر نشان می‌دهد چگونه می‌توان worksheet‌های ۱ و ۳ را به PNG رندر کرد، در حالی‌که spreadsheet دارای ۳ 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);
}

تقسیم worksheet‌ها به صفحات

GroupDocs.Viewer اسناد را به صفحات رندر می‌کند؛ در اینجا «صفحه» به ناحیه‌ای مستطیلی نسبتاً کوچک (مشابه صفحه نمایش یا کاغذ A4) اشاره دارد. از سوی دیگر، worksheet‌ها می‌توانند بسیار بزرگ باشند. به‌عنوان مثال، فرمت قدیمی ‌XLS حداکثر ۲۵۶ ستون و ۶۵۵۳۶ ردیف را پشتیبانی می‌کند، در حالی‌که فرمت جدیدتر ‌XLSX (Office Open XML Workbook) و Microsoft Excel هر دو تا ۱۶۳۸۴ ستون و ۱٬۰۴۸۵۷۶ ردیف را پشتیبانی می‌کنند. «جاسازی» worksheet‌ها در صفحات بخش مهمی از رندر صفحه‌گسترده‌ها با GroupDocs.Viewer است. برای اینکه یک worksheet داخل یک یا چند صفحه جای بگیرد، GroupDocs.Viewer عمل «تقسیم worksheet» را انجام می‌دهد؛ یعنی worksheet به بخش‌های مستطیلی متعدد تقسیم می‌شود و هر بخش روی یک صفحه جداگانه قرار می‌گیرد. پنج روش متفاوت برای این تقسیم وجود دارد که در ادامه توضیح داده می‌شوند.

نکته مهم: تمام این روش‌های تقسیم با همان روش تعریف می‌شوند — با فراخوانی یک متد استاتیک (factory method) خاص که یک نمونه از کلاس SpreadsheetOptions ایجاد می‌کند.

رندر کل worksheet در یک صفحه

SpreadsheetOptions.ForOnePagePerSheet()

ساده‌ترین راه — تقسیم را غیر فعال کرده و اندازهٔ صفحه را طوری تنظیم کنید که تمام محتوای worksheet در یک صفحه جا بگیرد. این گزینه زمانی مناسب است که از پیش بدانید worksheet کوچک است. اما اگر worksheet بزرگ باشد، ممکن است نتایج ناخوشایندی بدهد؛ به‌ویژه رندر به HTML می‌تواند باعث ایجاد فایل‌های حجیم (ده‌ها یا صدها MiB) شود که در مرورگرهای وب مشکل‌ساز می‌شود. در رندر به JPEG، اگر عرض یا ارتفاع بیش از ۶۵۵۳۵ پیکسل باشد، ممکن است خطا رخ دهد. بنابراین این حالت را فقط در مواقع موردنیاز استفاده کنید.

رندر worksheet در یک صفحه

تقسیم worksheet بر پایهٔ page breakها

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel به‌صورت خودکار page breakها را بر پایهٔ اندازهٔ کاغذ و تنظیمات صفحه (جهت، حاشیه‌ها) اضافه می‌کند. اگر به تب «View» رفته و حالت «Page Break Preview» را فعال کنید، خطوط آبی می‌بینید که worksheet را به بخش‌های مستطیلی تقسیم می‌کنند؛ هر بخش به‌صورت «Page 1»، «Page 2» و غیره برچسب‌گذاری شده است. این همان روشی است که Excel برای تقسیم به صفحات پیشنهاد می‌دهد.

در این روش GroupDocs.Viewer همانند Excel عمل می‌کند و worksheet‌ها را بر اساس page breakها تقسیم می‌نماید.

قابل ذکر است که این گزینه (تقسیم بر پایهٔ page break) به‌صورت پیش‌فرض در ویژگی BaseViewOptions.SpreadsheetOptions تنظیم شده؛ بنابراین وقتی یک نمونه از کلاس گزینه‌های نمایش می‌سازید، گزینه ForRenderingByPageBreaks() به‌طور پیش‌فرض فعال است.

رندر فقط محدودهٔ چاپ (Print Area)

SpreadsheetOptions.ForRenderingPrintArea()

در کنار page breakها، Excel مفهوم «Print Area» را دارد. Print Area مجموعه‌ای از یک یا چند محدودهٔ سلولی است که برای چاپ تعیین شده‌اند؛ هر محتوایی خارج از این محدوده چاپ نمی‌شود. برای افزودن یک محدوده به Print Area، به تب «Page Layout» بروید، روی دکمه «Print Area» کلیک کنید و سپس گزینه «Set Print Area» را انتخاب کنید (نمایش صفحهٔ زیر). برای افزودن محدودهٔ دیگر، همان مسیر را طی کنید و گزینه «Add to Print Area» را انتخاب کنید. در حالت «Page Break Preview» تمام محدوده‌های Print Area قابل مشاهده هستند.

رندر فقط Print Area

رندر Print Area و تقسیم بر پایهٔ page breakها

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer ویژگی منحصربه‌فردی دارد: ترکیب Print Area و page breakها در یک حالت. در این حالت، همهٔ محدوده‌های Print Area و page breakها همزمان لحاظ می‌شوند تا worksheet روی صفحات تقسیم شود.

در تصویر زیر خط قرمز نشان‌دهندهٔ Print Area و خط آبی نشان‌دهندهٔ page breakها است.

رندر Print Area و تقسیم بر پایهٔ page breakها

تقسیم worksheet به صفحات به‌صورت دستی بر پایهٔ ردیف‌ها و ستون‌ها

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

گاهی هیچ‌یک از روش‌های تقسیم قبلی قابل‌قبول نیست یا فرمت صفحه‌گسترده (مانند CSV) از page breakها و Print Area پشتیبانی نمی‌کند. در چنین مواردی GroupDocs.Viewer امکان تعیین دستی تعداد ردیف‌ها و/یا تعداد ستون‌هایی که باید در هر صفحه باشند را می‌دهد. به‌صورت خلاصه، تفاوت تقسیم فقط بر پایهٔ ردیف‌ها و تقسیم بر پایهٔ ردیف‌ها و ستون‌ها در تصویر زیر نشان داده شده است.

اگر overload اول متد ForSplitSheetIntoPages (یک پارامتر) استفاده شود، تقسیم تنها بر پایهٔ ردیف‌ها فعال می‌شود. اگر overload دوم (دو پارامتر) استفاده شود، تقسیم بر پایهٔ ردیف‌ها و ستون‌ها فعال می‌گردد.

تقسیم worksheet به صفحات به‌صورت دستی بر پایهٔ ردیف‌ها و ستون‌ها

تنظیم گزینه‌های تکمیلی

تمام موارد فوق برای رندر صفحه‌گسترده‌ها با GroupDocs.Viewer اساسی و کافی هستند؛ اما گزینه‌های تکمیلی دیگری نیز وجود دارند که اجباری نیستند اما به کاربران امکان می‌دهند نتیجهٔ رندر را دقیق‌تر تنظیم کنند.

بعضی از این گزینه‌ها به‌صورت ویژگی‌های کلاس SpreadsheetOptions ارائه می‌شوند (که از طریق ویژگی SpreadsheetOptions در کلاس گزینه‌های نمایش در دسترس است). برخی دیگر در کلاس انتزاعی ViewOptions که بین چهار حالت رندر مشترک است، قرار دارند.

رندر عنوان‌های ردیف و ستون

هنگامی که MS Excel یا برنامه مشابهی یک سند صفحه‌گسترده را باز می‌کند، عنوان‌های ردیف و ستون را نمایش می‌دهد؛ ستون‌ها با حروف (A, B, C, AA, AB, …) و ردیف‌ها با اعداد (1, 2, 3, …، 1048576) نام‌گذاری می‌شوند. به‌طور پیش‌فرض GroupDocs.Viewer این عنوان‌ها را نشان نمی‌دهد، زیرا متعلق به رابط کاربری برنامهٔ پردازش جدول است، نه به خود سند. می‌توانید با ویژگی boolean RenderHeadings این رفتار را تغییر دهید. پیش‌فرض این گزینه غیرفعال (false) است؛ وقتی به true تنظیم شود، عنوان‌های ردیف و ستون در سند خروجی ظاهر می‌شوند (نمونهٔ صفحهٔ زیر).

رندر عنوان‌های ردیف و ستون

رندر خطوط شبکه (gridlines) worksheet

این گزینه شبیه گزینهٔ قبلی است. به‌طور پیش‌فرض GroupDocs.Viewer خطوط شبکه بین سلول‌ها را نشان نمی‌دهد، زیرا این خطوط بخشی از نمایشگر جدول نیستند. با تنظیم ویژگی boolean RenderGridLines به true می‌توانید رفتار Excel را شبیه‌سازی کنید؛ خطوط شبکه در سند خروجی ظاهر می‌شوند (نمونهٔ صفحهٔ زیر).

رندر خطوط شبکه worksheet

کنترل سرریز متن سلول

سناریوی رایجی وجود دارد که متن داخل یک سلول از فضای خود فراتر می‌رود. برای حل این مشکل GroupDocs.Viewer ویژگی خاصی به نام SpreadsheetOptions.TextOverflowMode ارائه می‌دهد. این ویژگی از نوع enum با نام یکسان است و چهار مقدار دارد که در ادامه توضیح داده می‌شوند.

OverlayIfNextIsEmpty

به‌طور پیش‌فرض مقدار این ویژگی OverlayIfNextIsEmpty است که رفتار پیش‌فرض Excel را شبیه‌سازی می‌کند. متن می‌تواند به سلول‌های مجاور سرریز شود، اما تنها وقتی که این سلول‌ها خالی باشند. اگر سلول‌های مجاور داده داشته باشند، متن سرریز شده قطع می‌شود.

مقدار enum OverlayIfNextIsEmpty

در تصویر بالا، فایل HTML حاصل از رندر یک فایل XLSX با مقدار OverlayIfNextIsEmpty نمایش داده شده است. در سلول «B2» متن طولانی وجود دارد که چون سلول «C2» خالی نیست، متن قطع می‌شود. سلول «C3» متن طولانی دیگری دارد که به دلیل خالی بودن سلول‌های «D2» و «E2»، سرریز می‌شود.

Overlay

مقدار Overlay کمی شبیه مقدار قبلی است، اما رفتار تهاجمی‌تری دارد: متن طولانی که داخل سلول اصلی جا نمی‌شود، همیشه به سلول‌های مجاور سرریز می‌شود، صرف‌نظر از اینکه آن سلول‌ها داده داشته باشند یا نه. داده‌های موجود در سلول‌های مجاور در این حالت پاک می‌شوند.

مقدار enum Overlay

در تصویر فوق می‌توانید مشاهده کنید که متن طولانی سلول «B2» به سلول‌های «C2»، «D2»، «E2» و «F2» سرریز شده و متن‌های قبلی این سلول‌ها حذف شده‌اند.

HideText

مقدار HideText برعکس رفتار Overlay عمل می‌کند؛ به‌جای سرریز، متن که در محدودهٔ سلول خود جا نمی‌شود صرفاً قطع می‌شود، حتی اگر فضای خالی در سلول‌های مجاور موجود باشد.

مقدار enum HideText

در تصویر بالا می‌توانید ببینید که در سلول «C3» متن به‌دلیل وجود فضای خالی در سلول‌های «D3» و …، همچنان قطع می‌شود.

AutoFitColumn

مقدار AutoFitColumn مشکل را با رویکرد دیگری حل می‌کند؛ عرض ستون را برای جای دادن متن هر سلول افزایش می‌دهد. بنابراین بدون در نظر گرفتن طول متن داخل سلول، عرض ستون (ها) به‌گونه‌ای تنظیم می‌شود که کل رشته جا بگیرد.

مقدار enum AutoFitColumn

در تصویر فوق می‌بینید که این روش کار می‌کند. البته در برخی موارد (به‌ویژه متن‌های بسیار طولانی) ممکن است صفحه به‌طبیعی بسیار عریض شود و نیاز به اسکرول افقی داشته باشید.

رندر ردیف‌ها و ستون‌های مخفی

Microsoft Excel و برنامه‌های مشابه امکان مخفی کردن ردیف‌ها یا ستون‌های خاصی را فراهم می‌کنند. به‌طور پیش‌فرض GroupDocs.Viewer این ردیف‌ها/ستون‌های مخفی را رندر نمی‌کند؛ اما می‌توانید با تنظیم ویژگی‌های boolean زیر این رفتار را تغییر دهید:

هنگامی که این ویژگی‌ها به true تنظیم شوند، ردیف‌ها و ستون‌های مخفی در فایل خروجی (HTML، PDF، PNG یا JPEG) نمایش داده می‌شوند.

رندر Worksheetهای مخفی

مانند ردیف‌ها و ستون‌های مخفی، یک فایل صفحه‌گسترده می‌تواند یک یا چند Worksheet مخفی داشته باشد. پیش‌فرض GroupDocs.Viewer این Worksheetهای مخفی را رندر نمی‌کند، اما می‌توانید با تنظیم ویژگی RenderHiddenPages به true این رفتار را عوض کنید. توجه داشته باشید که این ویژگی در کلاس انتزاعی BaseViewOptions قرار دارد، نه در SpreadsheetOptions.

حذف ردیف‌ها و ستون‌های خالی

برخی صفحه‌گسترده‌ها «پراک» هستند؛ یعنی فضای خالی زیادی دارند که ممکن است حجم خروجی را به‌طور ناخواسته افزایش دهد. GroupDocs.Viewer امکان حذف ردیف‌ها و ستون‌های خالی را ارائه می‌دهد. اگر این ویژگی فعال باشد، ردیف‌ها/ستون‌های خالی در خروجی HTML، PDF، PNG و JPEG حذف می‌شوند. این رفتار توسط دو ویژگی boolean زیر کنترل می‌شود:

حذف ردیف‌ها و ستون‌های خالی

در تصویر فوق می‌توانید ببینید که هر دو ویژگی SkipEmptyRows و SkipEmptyColumns فعال شده‌اند.

رندر یا مخفی‌کردن نظرات سلولی

سلول‌های یک سند صفحه‌گسترده می‌توانند نظراتی داشته باشند و به‌صورت پیش‌فرض GroupDocs.Viewer همهٔ این نظرات را رندر می‌کند. می‌توانید این رفتار را با تنظیم ویژگی BaseViewOptions.RemoveComments به true غیرفعال کنید؛ به این ترتیب هیچ‌گونه نظری رندر نخواهد شد. این ویژگی در کلاس انتزاعی BaseViewOptions قرار دارد، نه در SpreadsheetOptions.

رندر یا مخفی‌کردن نظرات سلولی

در تصویر فوق، فایل XLSX با نظرات سلولی به فرمت PNG رندر شده است؛ نظر سلول «E2» در خروجی PNG دیده می‌شود.

تنظیم حاشیه‌های Worksheet در صفحات PDF خروجی

زمانی که Worksheetها را به فرمت PDF رندر می‌کنید، می‌توانید حاشیه‌های صفحه را کنترل کنید؛ یعنی فاصله‌ برحسب سانتی‌متر از لبهٔ صفحه تا محتوای آن. برای این منظور چهار ویژگی زیر وجود دارد:

به‌صورت پیش‌فرض این چهار ویژگی مقدار منفی دارند؛ به این معنی که حاشیه‌های پیش‌فرض توسط GroupDocs.Viewer اعمال می‌شود. می‌توانید این مقادیر را به‌صورت صریح تنظیم کنید. لازم به ذکر است که حاشیه‌ها فقط در زمانی اعمال می‌شوند که هدف خروجی PDF باشد.

کد زیر نمونه‌ای از ایجاد گزینه PdfViewOptions، تنظیم چهار حاشیه و رندر سند است:

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

نتیجهٔ این تنظیمات در تصویر زیر قابل مشاهده است:

تنظیم حاشیه‌های Worksheet در صفحات PDF خروجی

نتیجه‌گیری

فرمت‌های صفحه‌گسترده پیچیده‌اند و اسناد می‌توانند محتوای بسیار متفاوتی با انواع و طول‌های متنوع داشته باشند. در بسیاری از موارد رندر یک سند پیچیده صفحه‌گسترده با گزینه‌های پیش‌فرض امکان‌پذیر نیست؛ به همین دلیل GroupDocs.Viewer مجموعهٔ کاملی از ویژگی‌ها را فراهم می‌آورد که به کاربران اجازه می‌دهد رندر را دقیقاً مطابق نیازهای خود تنظیم کنند.

مطالب مرتبط

دریافت نسخهٔ آزمایشی رایگان

می‌توانید نسخهٔ آزمایشی رایگان GroupDocs.Viewer برای .NET را از releases.groupdocs.com دانلود کنید. همچنین می‌توانید یک لایسنس موقت برای امتحان تمام ویژگی‌ها و قابلیت‌ها بدون محدودیت از اینجا دریافت کنید.