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

EmailConfig

فرمت‌ها: 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`	فعال‌سازی ضد‌لبه‌دار (anti-aliasing).
`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 است.

پیکربندی	ویژگی	پیش‌فرض	رفتار
`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` مؤثر	DPI افقی صریح؛ در غیر این صورت `ImageResolution`، سپس 100.
`int`	`VerticalResolution`	`100` مؤثر	DPI عمودی صریح؛ در غیر این صورت `ImageResolution`، سپس 100.
`int`	`AnimationFrameDelayMs`	`100`	تاخیر فریم انیمیشن چندفریم؛ زمان‌بندی GIF از واحدهای ۱۰ میلی‌ثانیه استفاده می‌کند.
`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`	نمونه جدید	تنظیمات مسیر 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`	نمونه جدید	تنظیمات مسیر PDF.
`bool`	`ExportPdfA`	`true`	خروجی PDF/A بایگانی.

HtmlConfig، EpubConfig، MhtConfig و XpsConfig

هر چهار به‌صورت پیش‌فرض 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 → 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
};