مرور کلی

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

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

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

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

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

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

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 صحبت می‌کنیم. هر Spreadsheet حداقل یک worksheet دارد. در اکثر نرم‌افزارهای پردازش جدول مانند Microsoft Excel، worksheets به‌صورت تب‌ها نمایش داده می‌شوند. برخی فرمت‌های Spreadsheet ممکن است فقط یک worksheet داشته باشند؛ این شامل تمام فرمت‌های متنی مبتنی بر جداکننده (مانند CSV، TSV و غیره) می‌شود.

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

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

مثال زیر نشان می‌دهد چگونه worksheet اول و سوم را در یک Spreadsheet که دارای ۳ worksheet است به PNG رندر کنیم.

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

تقسیم worksheets به صفحات

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

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

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

SpreadsheetOptions.ForOnePagePerSheet()

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

Render worksheet on one page

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

SpreadsheetOptions.ForRenderingByPageBreaks()

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

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

لازم به ذکر است که این گزینه — تقسیم worksheet بر اساس page break — گزینهٔ پیش‌فرض ویژگی BaseViewOptions.SpreadsheetOptions است؛ بنابراین هنگام ایجاد یک نمونه از کلاس گزینهٔ view، گزینهٔ [ForRenderingByPageBreaks()] به‌صورت پیش‌فرض انتخاب می‌شود.

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

SpreadsheetOptions.ForRenderingPrintArea()

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

Render only print area

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

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

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

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

Render print area and split by page breaks

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

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

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

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

Split worksheet into pages manually by rows and columns

تنظیم گزینه‌های اضافی

تمام موارد توضیح داده‌شده در بالا برای رندر Spreadsheetها با GroupDocs.Viewer اساسی و کافی هستند. با این حال گزینه‌های اضافی متعددی وجود دارد که الزامی نیستند، اما به کاربران اجازه می‌دهند نتیجهٔ رندر را دقیق‌تر تنظیم کنند.

برخی از این گزینه‌ها به‌صورت ویژگی‌های کلاس SpreadsheetOptions ارائه می‌شوند که خود از طریق ویژگی SpreadsheetOptions در کلاس گزینهٔ view قابل دسترسی است. برخی دیگر در کلاس انتزاعی ViewOptions قرار دارند که برای تمام ۴ حالت رندر مشترک است.

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

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

Render row and column headings

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

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

Render worksheet gridlines

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

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

OverlayIfNextIsEmpty

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

OverlayIfNextIsEmpty enum value

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

Overlay

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

Overlay enum value

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

HideText

حالت TextOverflowMode.HideText برعکس حالت Overlay عمل می‌کند — به‌جای سرریز، متن که در محدودهٔ سلول خود جا نمی‌شود، صرف‌نظر از وجود فضای خالی در سلول(های) مجاور، قطع می‌شود.

HideText enum value

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

AutoFitColumn

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

AutoFitColumn enum value

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

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

Microsoft Excel و سایر پردازشگرهای جدول امکان مخفی‌کردن ردیف‌ها و ستون‌های خاص را فراهم می‌کنند. به‌صورت پیش‌فرض GroupDocs.Viewer این ردیف‌ها و ستون‌های مخفی را رندر نمی‌کند، اما می‌توان این رفتار را تغییر داد. ویژگی‌های ViewOptions.SpreadsheetOptions.RenderHiddenRows و ViewOptions.SpreadsheetOptions.RenderHiddenColumns وقتی به true تنظیم شوند، ردیف‌ها و ستون‌های مخفی را در فایل خروجی (HTML، PDF، PNG یا JPEG) نمایش می‌دهند.

رندر worksheets مخفی

همانند ردیف‌ها و ستون‌های مخفی، یک فایل Spreadsheet می‌تواند یک یا چند worksheet مخفی داشته باشد. به‌صورت پیش‌فرض GroupDocs.Viewer این worksheets مخفی را رندر نمی‌کند. اما می‌توان با تنظیم ویژگی RenderHiddenPages به true این رفتار را تغییر داد. لازم به ذکر است که برخلاف ویژگی‌های قبلی، RenderHiddenPages در کلاس انتزاعی BaseViewOptions قرار دارد که برای تمام گزینه‌های view مشترک است.

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

برخی Spreadsheetها «پراکندگی» دارند — فضای خالی زیادی دارند که ممکن است فضای زیادی اشغال کند. GroupDocs.Viewer امکان حذف ردیف‌ها و ستون‌های خالی را از رندر فراهم می‌کند. اگر این ویژگی فعال باشد، ردیف‌ها و/یا ستون‌های خالی از خروجی HTML، PDF، PNG و JPEG حذف می‌شوند. ویژگی‌های boolean SpreadsheetOptions.SkipEmptyRows و SpreadsheetOptions.SkipEmptyColumns مسئول این عملکرد هستند.

Skip empty rows and columns

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

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

سلول‌های یک سند Spreadsheet ممکن است نظرات (comments) داشته باشند و به‌صورت پیش‌فرض GroupDocs.Viewer همهٔ آن‌ها را رندر می‌کند. اما می‌توان این رفتار را با ویژگی BaseViewOptions.RemoveComments غیرفعال کرد — اگر مقدار آن را به true تنظیم کنید، هیچ نظری رندر نخواهد شد. توجه داشته باشید این ویژگی در کلاس BaseViewOptions قرار دارد، نه در SpreadsheetOptions.

Render or hide cell comments

در تصویر بالا رندر یک فایل XLSX با نظرات سلول‌ها به فرمت PNG با گزینه‌های پیش‌فرض نشان داده شده است — نظر سلول «E2» در فایل PNG نهایی حضور دارد.

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

هنگام رندر worksheets به فرمت 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);
}

تصویر زیر نتیجه را نشان می‌دهد:

Set worksheet margins in the output PDF pages

نتیجه‌گیری

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

مطالب مرتبط

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

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