پیکربندی‌های قالب – مستندات Doconut

هر سند با یک پیاده‌سازی BaseConfig باز می‌شود. یکی را به OpenDocumentAsync پاس دهید یا بگذارید فهرست قالب پیش‌فرض خود را ایجاد کند. تمام کلاس‌های زیر در فضای نام Doconut قرار دارند.

آن فضای نام واحد جدید است. کتابخانه قبلی .NET Standard این انواع را در Doconut.Configs، Doconut.Configs.View و Doconut.Models پخش کرده بود. نام‌های نوع تغییر نکرده‌اند — در اکثر فایل‌ها ویرایش کامل حذف دو خط using است. راهنمای راهنمای مهاجرت را ببینید.

csharp

var token = await viewer.OpenDocumentAsync(path, new PdfConfig
{
    AllowSearch = true,
    AllowCopy   = true,
    ImageResolution = 150
});

وراثت و تنظیمات تو در تو PDF

هر قالب پنج ویژگی BaseConfig را به ارث می‌برد. قالب‌هایی که می‌توانند از طریق PDF بازنشر شوند، یک PdfConfig تو در تو را ارائه می‌دهند. در WordConfig، ExcelConfig و PptConfig، AllowSearch و AllowCopy ویژگی‌های راحتی هستند که مقدار PdfConfig تو در تو را می‌خوانند و می‌نویسند.

DefaultRender = true رندر کننده بومی قالب را انتخاب می‌کند. در قالب‌هایی که بازنشر PDF دارند، false ابتدا به یک PDF در حافظه تبدیل می‌شود و سپس از نمایشگر PDF استفاده می‌کند. این مسیر اغلب برای جستجوی متن‑مختصات مفید است، اما تبدیل اضافی هزینه دارد.

مگر آنکه خلاف آن ذکر شده باشد، جداول مقادیر پیش‌فرض سازنده/ویژگی را نشان می‌دهند. فهرست قالب خودکار به‌طور عمدی دو مورد از آن‌ها را بازنویسی می‌کند: ExcelConfig را با SplitWorksheets = true و MhtConfig را با DefaultRender = false ایجاد می‌کند.

BaseConfig

نوع	ویژگی	پیش‌فرض	رفتار
`int`	`ImageResolution`	`0`	`0` از مقدار پیش‌فرض قالب استفاده می‌کند. بازه صریح معتبر ۲۵‑۳۰۰ DPI است؛ انتساب‌های نامعتبر نادیده گرفته می‌شوند.
`string`	`DocumentCulture`	`""`	محلی برای تاریخ‌ها و اعداد. مقادیر غیر خالی حذف فضا می‌شوند؛ انتساب‌های خالی نادیده گرفته می‌شوند.
`string`	`Password`	`""`	رمز عبور سند محافظت‌شده. `DocOptions.Password` به‌صورت خودکار اینجا کپی می‌شود.
`bool`	`ShowUI`	`true`	ویژگی سازگاری؛ رندر کننده فعلی از آن برای کنترل نوار ابزار مرورگر استفاده نمی‌کند.
`bool`	`CachePages`	`true`	تصاویر صفحات رندر شده را برای جلسه سند کش می‌کند.

PdfConfig

قالب‌ها: PDF. DPI پیش‌فرض: 200.

نوع	ویژگی	پیش‌فرض	رفتار
`bool`	`DefaultRender`	`true`	کلید سازگاری. کارخانه فعلی از نمایشگر بومی PDF استفاده می‌کند.
`bool`	`AllowSearch`	`false`	ساخت/استفاده از فهرست جستجوی متن PDF. برای درخواست‌ها نیاز به قابلیت لایسنس Search دارد.
`bool`	`AllowCopy`	`false`	اجازه عملیات انتخاب/کپی متن.
`bool`	`ExtractHyperlinks`	`false`	استخراج مستطیل‌های لینک برای پوشش‌های کلاینت.
`int`	`HyperlinksPageCount`	`0`	حداکثر صفحات اسکن‌شده برای لینک‌ها؛ `0` به معنای همه صفحات است.
`bool`	`CompressImages`	`false`	فشرده‌سازی تصاویر جاسازی‌شده قبل از رندر.
`int`	`CompressQuality`	`100`	کیفیت JPEG که هنگام فعال بودن فشرده‌سازی استفاده می‌شود.
`bool`	`ResizeImages`	`false`	تغییر اندازه تصاویر جاسازی‌شده قبل از رندر.
`int`	`ResizeResolution`	`300`	DPI هدف برای تصاویر تغییر اندازه‌یافته.
`bool`	`CompressFast`	`false`	ترجیح مسیر فشرده‌سازی سریع‌تر و با کیفیت پایین‌تر.
`bool`	`FixInvalidImages`	`false`	تلاش برای تعمیر تصاویر جاسازی‌شده نامعتبر.
`bool`	`SplitSegments`	`false`	بازآوری کلمات تقسیم‌شده در بخش‌های خط برای بهبود جستجو/کپی.

showHyperlinks در ViewerConfig پوشش کلاینت را کنترل می‌کند، در حالی که ExtractHyperlinks استخراج سرور را کنترل می‌کند. هر دو را فعال کنید.

WordConfig

قالب‌ها: DOC، DOCX، DOCM، DOT، DOTX، DOTM، RTF، ODT، OTT، XML. DPI پیش‌فرض: 200.

نوع	ویژگی	پیش‌فرض	رفتار
`bool`	`DefaultRender`	`true`	رندر بومی Word؛ `false` از بازنشر PDF استفاده می‌کند.
`PdfConfig`	`PdfConfig`	new instance	تنظیماتی که توسط مسیر PDF/جستجو استفاده می‌شود.
`DocPaperSize`	`PaperSize`	`A4`	اندازه کاغذ خروجی. از `Custom` با عرض/ارتفاع استفاده کنید.
`int`	`PaperWidth`	`595`	عرض سفارشی به نقطه.
`int`	`PaperHeight`	`841`	ارتفاع سفارشی به نقطه.
`bool`	`RemovePaperMargin`	`false`	حذف حاشیه‌های صفحه سند.
`bool`	`RenderPageColor`	`true`	حفظ رنگ صفحه تنظیم‌شده در Word؛ `false` صفحات سفید رندر می‌کند.
`bool`	`ExportPdfA`	`false`	استفاده از PDF/A بایگانی در مسیر PDF.
`Encoding?`	`FileEncoding`	`null`	بازنویسی رمزگذاری منبع.
`string`	`FontInfo`	`""`	اطلاعات جایگزینی قلم.
`string[]?`	`FontFolders`	`null`	دایرکتوری‌های قلم اضافی، به‌ویژه در لینوکس/کانتینرها مفید است.
`bool`	`AllowSearch`	`false`	به `PdfConfig.AllowSearch` واگذار می‌شود.
`bool`	`AllowCopy`	`false`	به `PdfConfig.AllowCopy` واگذار می‌شود.
`TableAutoFitBehavior`	`AutoFitAllTables`	`None`	`None`، `AutoFitToContents` یا `AutoFitToWindow`.

پیکربندی Excel

قالب‌ها: XLS, XLSX, XLSM, XLSB, XLTX, XLTM, ODS, CSV. DPI پیش‌فرض: 200.

نوع	ویژگی	پیش‌فرض	رفتار
`bool`	`DefaultRender`	`true`	رندر بومی شیت؛ `false` از تغییر مسیر PDF استفاده می‌کند.
`PdfConfig`	`PdfConfig`	`new instance`	تنظیمات مسیر PDF/جستجو.
`ExcelPaperSize`	`PaperSize`	`PaperA4`	اندازه کاغذ خروجی.
`double`	`PaperMargins`	`0.25`	حاشیه‌های صفحه بر حسب اینچ.
`bool`	`PaperLandscape`	`true`	رندر شیت به حالت افقی.
`bool`	`AutoFitContents`	`false`	تنظیم خودکار ارتفاع ردیف‌ها و عرض ستون‌ها.
`bool`	`RemoveEmptyContent`	`true`	فشرده‌سازی خروجی با حذف محتوای خالی.
`bool`	`CalculateFormula`	`true`	محاسبه مجدد فرمول‌ها قبل از رندر.
`bool`	`ShowRowColumnHeaders`	`true`	شامل کردن سرصفحه‌های ردیف/ستون.
`bool`	`ExportPdfA`	`false`	استفاده از PDF/A در مسیر PDF.
`bool`	`SplitWorksheets`	`false`	نگه داشتن شیت‌ها به‌صورت گروه‌های صفحه جداگانه.
`bool`	`ShowEmptyWorkSheets`	`false`	شامل کردن شیت‌های خالی.
`bool`	`ExportLandscape`	`false`	اجبار خروجی به حالت افقی.
`bool`	`ExportOnePagePerSheet`	`false`	متناسب‌سازی هر شیت با یک صفحه خروجی.
`bool`	`MemoryOptimizationPreference`	`true`	کاهش حداکثر حافظه، شاید با کاهش کمی سرعت.
`bool`	`AutoTrimWorksheetRenderRange`	`true`	رندر فقط بازه استفاده‌شده قابل مشاهده وقتی محدوده چاپ صریح وجود ندارد.
`bool`	`AutoTrimPreserveExistingPrintArea`	`true`	حفظ نواحی چاپ تعریف‌شده در کتاب کار هنگام برش خودکار.
`string?`	`PrintArea`	`null`	بازه صریح مانند `"A1:Z100"`.
`bool`	`PrintGridlines`	`false`	چاپ خطوط شبکه شیت.
`bool`	`PrintHeadings`	`false`	چاپ سرصفحه‌های ردیف/ستون.
`List<string>`	`SheetNames`	empty	محدود کردن رندر به شیت‌های نام‌گذاری‌شده.
`CustomStyleCell?`	`CustomStyles`	`null`	بازنویسی‌های اختیاری قالب‌بندی تاریخ/دهدهی/عدد صحیح.
`bool`	`AllowSearch`	`false`	به `PdfConfig.AllowSearch` واگذار می‌شود.
`bool`	`AllowCopy`	`false`	به `PdfConfig.AllowCopy` واگذار می‌شود.

CustomStyleCell متغیرهای CustomStyleDateTime، CustomStyleNumberDecimal و CustomStyleNumberInteger را که همه رشته‌های nullable هستند، در دسترس می‌گذارد.

new ExcelConfig() مقدار SplitWorksheets را به false تنظیم می‌کند؛ باز کردن یک فایل Excel بدون پیکربندی صریح از فهرست قالب‌ها استفاده می‌کند که آن را به true تنظیم می‌نماید.

پیکربندی Ppt

قالب‌ها: PPT, PPTX, PPTM, PPSX, PPSM, POT, POTX, POTM, ODP. DPI پیش‌فرض: 200.

نوع	ویژگی	پیش‌فرض	رفتار
`bool`	`DefaultRender`	`true`	رندر بومی اسلاید؛ `false` از تغییر مسیر PDF استفاده می‌کند.
`bool`	`FastLoad`	`false`	اجتناب از رندر اسلاید اول هنگام باز کردن؛ استفاده از متادیتا و رندر بر حسب نیاز.
`PdfConfig`	`PdfConfig`	`new instance`	تنظیمات رفتار PDF/جستجو.
`string`	`FontInfo`	`""`	اطلاعات جایگزینی قلم.
`string[]?`	`FontFolders`	`null`	دایرکتوری‌های قلم اضافی.
`bool`	`AllowSearch`	`false`	به `PdfConfig.AllowSearch` واگذار می‌شود.
`bool`	`AllowCopy`	`false`	به `PdfConfig.AllowCopy` واگذار می‌شود.

در لینوکس و macOS، رندر ارائه با موتور فعلی به libgdiplus و System.Drawing.EnableUnixSupport=true نیاز دارد. قلم‌های استفاده‌شده در ارائه را نصب کنید یا FontFolders را فراهم کنید.

پیکربندی Cad

قالب‌ها: DWG, DXF, DGN. DPI پیش‌فرض: 200.

نوع	ویژگی	پیش‌فرض	رفتار
`bool`	`DefaultRender`	`true`	رندر بومی CAD؛ `false` از تغییر مسیر PDF استفاده می‌کند.
`PdfConfig`	`PdfConfig`	`new instance`	تنظیمات مسیر PDF.
`bool`	`ExportPdfA`	`false`	خروجی PDF/A بایگانی.
`bool`	`ShowColor`	`true`	رنگ به‌جای تک‌رنگ.
`bool`	`WhiteBackground`	`true`	پس‌زمینه سفید به‌جای سیاه.
`short`	`LineWidth`	`25`	عرض خط CAD.
`bool`	`ShowLayouts`	`false`	رندر تب‌های طرح‌بندی.
`bool`	`ShowModel`	`true`	رندر فضای مدل.
`bool`	`Check3DSolid`	`true`	پردازش اجسام سه‌بعدی.
`bool`	`ExportAllLayouts`	`false`	خروجی تمام طرح‌بندی‌ها، نادیده‌گیری انتخاب مدل/طرح‌بندی.
`bool`	`LimitMinimumSize`	`false`	`MinimumSize` اعمال می‌شود.
`int`	`MinimumSize`	`700`	حداقل اندازه خروجی بر حسب پیکسل.
`bool`	`LimitMaximumSize`	`false`	`MaximumSize` اعمال می‌شود.
`int`	`MaximumSize`	`700`	حداکثر اندازه خروجی بر حسب پیکسل.
`bool`	`ShowAllLayoutsDgn`	`false`	شامل تمام طرح‌بندی‌های DGN.
`bool`	`AutomaticLayoutScaling`	`true`	مقیاس‌گذاری خودکار طرح‌بندی‌ها.
`float`	`PdfMargins`	`0.5`	حاشیه PDF بر حسب اینچ.
`RenderQuality`	`QualityImage`	`Low`	کیفیت رستر: `Low`، `Medium` یا `High`.
`RenderQuality`	`QualityText`	`Medium`	کیفیت متن: `Low`، `Medium` یا `High`.

پیکربندی ایمیل

فرمت‌ها: EML، EMLX، MSG. DPI پیش‌فرض: 200.

نوع	ویژگی	پیش‌فرض	رفتار
`bool`	`DefaultRender`	`true`	رندر بومی ایمیل؛ `false` از مسیر PDF استفاده می‌کند.
`PdfConfig`	`PdfConfig`	new instance	تنظیمات مسیر PDF.
`Encoding?`	`EmailEncoding`	`null`	بازنویسی رمزگذاری پیام.
`Encoding?`	`SubjectEncoding`	`null`	بازنویسی رمزگذاری موضوع.
`Encoding?`	`BodyEncoding`	`null`	بازنویسی رمزگذاری بدنه.
`bool`	`SkipExternalImages`	`false`	بارگذاری تصاویر مرجع از راه دور انجام نمی‌شود. برای ایمیل‌های غیرقابل اعتماد توصیه می‌شود.
`bool`	`RemoveLastWhitePage`	`false`	حذف صفحه سفید انتهایی.
`bool`	`UseAntiAliasing`	`false`	فعال‌سازی anti-aliasing.
`bool`	`UseHighQualityRendering`	`false`	ترجیح رندر تمیزتر اما کندتر.
`TimeSpan?`	`TimeZoneOffset`	`null`	بازنویسی منطقه زمانی استفاده‌شده برای تاریخ‌ها.
`bool`	`ForcePageSize`	`false`	اجبار به ابعاد ثابت صفحه.

پیکربندی تصویر، پیکربندی تیف و پیکربندی PSD

ImageConfig شامل JPG، JPEG، JPE، PNG، BMP، GIF، ICO، EPS، TGA، WEBP، CDR، CMX، DNG، EMF، WMF، AVIF و SVG است. DPI پیش‌فرض آن 100 است.

پیکربندی	ویژگی	پیش‌فرض	رفتار
`ImageConfig`	`MaxImagePixelSize`	`3000`	حداکثر عرض/ارتفاع. `0` به معنای نامحدود است؛ مقادیر غیرصفر زیر ۵۰ نادیده گرفته می‌شوند.
`ImageConfig`	`TransparentPng`	`true`	حفظ شفافیت PNG؛ `false` از پس‌زمینه سفید استفاده می‌کند.
`TiffConfig`	بدون ویژگی‌های اضافه	DPI `200`	فقط از `BaseConfig` استفاده می‌کند؛ از TIFF چندصفحه‌ای پشتیبانی می‌کند.
`PsdConfig`	`MaxImagePixelSize`	`3000`	همان اعتبارسنجی `0`/حداقل ۵۰ همانند `ImageConfig`؛ DPI پیش‌فرض `100` است.

پیکربندی دیکام

فرمت‌ها: DCM، IMA. DPI مؤثر پیش‌فرض: 100. نیاز به افزونه DICOM دارد.

نوع	ویژگی	پیش‌فرض	رفتار
`int`	`HorizontalResolution`	`100` مؤثر	DPI افقی صریح؛ در غیر این صورت `ImageResolution`، سپس 100.
`int`	`VerticalResolution`	`100` مؤثر	DPI عمودی صریح؛ در غیر این صورت `ImageResolution`، سپس 100.
`int`	`AnimationFrameDelayMs`	`100`	تاخیر فریم‌های چندفریم؛ زمان‌بندی GIF از واحدهای ۱۰ میلی‌ثانیه استفاده می‌کند.
`ushort`	`LoopCount`	`0`	`0` به‌صورت نامحدود حلقه می‌زند؛ مقادیر مثبت پس از آن تعداد متوقف می‌شوند.
`DicomDisplayMode`	`DisplayMode`	`AnimationAndFrames`	`AnimationOnly`، `FramesOnly` یا ترکیبی از نمای کلی به‌همراه فریم‌های ثابت.

پیکربندی متن

فرمت: TXT. DPI پیش‌فرض: 200.

نوع	ویژگی	پیش‌فرض	رفتار
`DocPaperSize`	`PaperSize`	`A4`	اندازه کاغذ خروجی.
`Encoding?`	`FileEncoding`	`null`	`null` از UTF-8 استفاده می‌کند.
`string`	`FontInformation`	`""`	اطلاعات قلم برای رندر متن.

از WordConfig استفاده کنید وقتی متن ساده به رفتار پیشرفته‌تری در چیدمان صفحه نیاز دارد.

پیکربندی پروژه

فرمت‌ها: MPP، MPPX، MPX. DPI پیش‌فرض: 200.

نوع	ویژگی	پیش‌فرض	رفتار
`bool`	`DefaultRender`	`true`	تصویر گانت بومی؛ `false` از مسیر PDF مبتنی بر متن استفاده می‌کند.
`PdfConfig`	`PdfConfig`	new instance	تنظیمات مسیر PDF.
`bool`	`ExportPdfA`	`true`	خروجی PDF/A بایگانی.
`MppPaperSize`	`PaperSize`	`Ledger`	اندازه کاغذ خروجی پروژه.
`MppTimeScale`	`TimeScale`	`Months`	`Days` یا `Months`.
`MppFormat`	`PresentationFormat`	`GanttChart`	`GanttChart`، `TaskUsage`، `ResourceUsage`، `ResourceSheet` یا `TaskSheet`.

برای جستجوی دقیق متن‑مختصات، از DefaultRender = false استفاده کنید.

پیکربندی ویژیو

فرمت‌ها: VSD، VSDX، VSS، VSSX، VST، VSTX، VDX، VSX، VSDM. DPI پیش‌فرض: 200.

نوع	ویژگی	پیش‌فرض	رفتار
`bool`	`DefaultRender`	`true`	رندر بومی نمودار؛ `false` از مسیر PDF استفاده می‌کند.
`PdfConfig`	`PdfConfig`	new instance	تنظیمات مسیر PDF.
`bool`	`ExportPdfA`	`true`	خروجی PDF/A بایگانی.

پیکربندی HTML، پیکربندی EPUB، پیکربندی MHT و پیکربندی XPS

هر چهار به‌صورت پیش‌فرض 200 DPI دارند و یک PdfConfig تو در تو را نمایش می‌دهند.

پیکربندی	فرمت‌ها	`DefaultRender`	ویژگی‌ها/رفتارهای اضافی
`HtmlConfig`	HTML، HTM	`true`	رندر بومی؛ برای مسیر جستجوی PDF مبتنی بر متن از `false` استفاده کنید.
`EpubConfig`	EPUB	`true`	رندر بومی؛ `false` از PDF استفاده می‌کند.
`MhtConfig`	MHT، MHTML	`true` در کلاس؛ `false` در فهرست خودکار	در کلاس `true`؛ در فهرست خودکار `false`. باز کردن عادی بدون پیکربندی از مسیر PDF قابل جستجو استفاده می‌کند. یک نمونه پیش‌فرض به‌صورت صریح ساخته‌شده به‌صورت بومی رندر می‌شود.
`XpsConfig`	XPS	`false`	به‌صورت پیش‌فرض از مسیر PDF استفاده می‌کند؛ برای رندر بومی تصویر `true` تنظیم کنید.

مثال‌های پیکربندی بر حسب خانواده

csharp

BaseConfig[] configs =
{
    new PdfConfig
    {
        AllowSearch = true,
        ExtractHyperlinks = true,
        HyperlinksPageCount = 0
    },
    new WordConfig
    {
        PaperSize = DocPaperSize.A4,
        RemovePaperMargin = false,
        FontFolders = new[] { "/usr/share/fonts/truetype" },
        AllowSearch = true
    },
    new ExcelConfig
    {
        PaperLandscape = true,
        AutoFitContents = true,
        CalculateFormula = true,
        SplitWorksheets = false,
        PrintGridlines = false
    },
    new PptConfig
    {
        FastLoad = true,
        FontFolders = new[] { "/usr/share/fonts/truetype" },
        AllowSearch = true
    },
    new CadConfig
    {
        ShowColor = true,
        WhiteBackground = true,
        ShowModel = true,
        ShowLayouts = false,
        QualityText = CadConfig.RenderQuality.High
    },
    new EmailConfig
    {
        SkipExternalImages = true,
        RemoveLastWhitePage = true,
        TimeZoneOffset = TimeSpan.Zero
    },
    new ImageConfig
    {
        MaxImagePixelSize = 3000,
        TransparentPng = true
    },
    new DicomConfig
    {
        DisplayMode = DicomDisplayMode.AnimationAndFrames,
        AnimationFrameDelayMs = 100,
        LoopCount = 0
    }
};

انتخاب بر اساس پسوند

csharp

static BaseConfig? ConfigForExtension(string extUpper) => extUpper switch
{
    ".DOC" or ".DOCX" or ".DOT" or ".DOTX" or ".ODT" => new WordConfig
    {
        AutoFitAllTables = WordConfig.TableAutoFitBehavior.AutoFitToWindow,
        PaperSize = DocPaperSize.Tabloid,
        PdfConfig = new PdfConfig { ExtractHyperlinks = true, HyperlinksPageCount = 5, AllowCopy = true }
    },
    ".PDF" => new PdfConfig { AllowSearch = true, AllowCopy = true },
    ".XLS" or ".XLSX" or ".ODS" or ".CSV" => new ExcelConfig { AllowSearch = true, AllowCopy = true },
    ".DCM" or ".IMA" => new DicomConfig { DisplayMode = DicomDisplayMode.AnimationAndFrames },
    // DefaultRender = false → PDF redirect → pixel-accurate native text search
    ".HTML" or ".HTM" => new HtmlConfig { DefaultRender = false },
    ".EML" or ".EMLX" or ".MSG" => new EmailConfig { DefaultRender = false },
    _ => null // fall back to the format's default config
};