پیکربندی‌های فرمت – 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` یا `AutoFitToWindow`.

ExcelConfig

فرمت‌ها: 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 تنظیم می‌نماید.

PptConfig

فرمت‌ها: 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 را فراهم کنید.

CadConfig

فرمت‌ها: 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`.

EmailConfig

فرمت‌ها: 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`	فعال‌سازی ضد‌لبه.
`bool`	`UseHighQualityRendering`	`false`	ترجیح رندر تمیزتر ولی کندتر.
`TimeSpan?`	`TimeZoneOffset`	`null`	بازنویسی منطقهٔ زمانی استفاده‌شده برای تاریخ‌ها.
`bool`	`ForcePageSize`	`false`	اجباری کردن ابعاد ثابت صفحه.

ImageConfig، TiffConfig و PsdConfig

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

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

DicomConfig

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

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

TxtConfig

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

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

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

ProjectConfig

فرمت‌ها: 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 استفاده کنید.

VisioConfig

فرمت‌ها: 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.

HtmlConfig، EpubConfig، MhtConfig و XpsConfig

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

Config	فرمت‌ها	`DefaultRender`	ویژگی‌ها/رفتارهای اضافی
`HtmlConfig`	HTML, HTM	`true`	رندر بومی؛ برای مسیر جستجوی PDF مبتنی بر متن از `false` استفاده کنید.
`EpubConfig`	EPUB	`true`	رندر بومی؛ `false` از PDF استفاده می‌کند.
`MhtConfig`	MHT, MHTML	`true` on the class; `false` in the automatic catalog	بازگشت پیش‌فرض بدون پیکربندی، از بازگردانی 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
};