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

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

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`, or `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 را نمایش می‌دهد، که همه رشته‌های قابل‌null هستند.

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`	پردازش اجسام 3D.
`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`	نمونه جدید	تنظیمات مسیر PDF.
`Encoding?`	`EmailEncoding`	`null`	بازنویسی رمزگذاری پیام.
`Encoding?`	`SubjectEncoding`	`null`	بازنویسی رمزگذاری موضوع.
`Encoding?`	`BodyEncoding`	`null`	بازنویسی رمزگذاری بدنه.
`bool`	`SkipExternalImages`	`false`	تصاویر ارجاع داده شده از راه دور بارگذاری نشوند. برای ایمیل‌های غیرقابل اعتماد توصیه می‌شود.
`bool`	`RemoveLastWhitePage`	`false`	حذف صفحه خالی انتهایی.
`bool`	`UseAntiAliasing`	`false`	فعال‌سازی ضد لبه‌دار.
`bool`	`UseHighQualityRendering`	`false`	ترجیح رندر تمیزتر و آهسته‌تر.
`TimeSpan?`	`TimeZoneOffset`	`null`	بازنویسی منطقه زمانی استفاده‌شده برای تاریخ‌ها.
`bool`	`ForcePageSize`	`false`	اجبار به ابعاد ثابت صفحه.

پیکربندی تصویر، پیکربندی TIFF و پیکربندی 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` است.

پیکربندی DICOM

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

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

پیکربندی TXT

قالب: 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`	نمونه جدید	تنظیمات مسیر PDF.
`bool`	`ExportPdfA`	`true`	خروجی PDF/A بایگانی.
`MppPaperSize`	`PaperSize`	`Ledger`	اندازه کاغذ خروجی پروژه.
`MppTimeScale`	`TimeScale`	`Months`	`Days` یا `Months`.
`MppFormat`	`PresentationFormat`	`GanttChart`	`GanttChart`، `TaskUsage`، `ResourceUsage`، `ResourceSheet`، یا `TaskSheet`.

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

پیکربندی Visio

قالب‌ها: VSD, VSDX, VSS, VSSX, VST, VSTX, VDX, VSX, VSDM. DPI پیش‌فرض: 200.

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

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

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

پیکربندی	قالب‌ها	`DefaultRender`	ویژگی‌ها/رفتارهای اضافی
`HtmlConfig`	HTML, HTM	`true`	رندر بومی؛ برای مسیر جستجوی PDF مبتنی بر متن از `false` استفاده کنید.
`EpubConfig`	EPUB	`true`	رندر بومی؛ `false` از PDF استفاده می‌کند.
`MhtConfig`	MHT, MHTML	`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 = ["/usr/share/fonts/truetype"],
        AllowSearch = true
    },
    new ExcelConfig
    {
        PaperLandscape = true,
        AutoFitContents = true,
        CalculateFormula = true,
        SplitWorksheets = false,
        PrintGridlines = false
    },
    new PptConfig
    {
        FastLoad = true,
        FontFolders = ["/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 → جستجوی متن بومی دقیق به پیکسل
    ".HTML" or ".HTM" => new HtmlConfig { DefaultRender = false },
    ".EML" or ".EMLX" or ".MSG" => new EmailConfig { DefaultRender = false },
    _ => null // به تنظیمات پیش‌فرض فرمت بازگردید
};