تكوينات الصيغ – 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` يستخدم القيمة الافتراضية للصيغة. النطاق الصريح الصالح هو 25‑300 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`	دلائل خطوط إضافية، مفيدة خصوصًا في Linux/الحاويات.
`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، جميعها سلاسل قابلة للفرغ.

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`.

على أنظمة Linux و 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`	معالجة المجسمات ثلاثية الأبعاد.
`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`	تمكين مضاد التعرج.
`bool`	`UseHighQualityRendering`	`false`	تفضيل عرض أنقى وأبطأ.
`TimeSpan?`	`TimeZoneOffset`	`null`	تجاوز المنطقة الزمنية المستخدمة للتواريخ.
`bool`	`ForcePageSize`	`false`	فرض أبعاد صفحة ثابتة.

ImageConfig, TiffConfig, and 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` يعني غير محدود؛ القيم غير الصفرية أقل من 50 تُهمل.
`ImageConfig`	`TransparentPng`	`true`	الحفاظ على شفافية PNG؛ `false` يستخدم خلفية بيضاء.
`TiffConfig`	لا توجد خصائص إضافية	DPI `200`	يستخدم فقط `BaseConfig`؛ يدعم TIFF متعدد الصفحات.
`PsdConfig`	`MaxImagePixelSize`	`3000`	نفس التحقق `0`/الحد الأدنى 50 كما في `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 يستخدم وحدات 10 مللي ثانية.
`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`	صورة Gantt الأصلية؛ `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, and XpsConfig

جميع الأربعة تُعطي DPI افتراضيًا قدره 200 وتكشف عن PdfConfig متداخلة.

التكوين	الصيغ	`DefaultRender`	خصائص/سلوك إضافي
`HtmlConfig`	HTML, HTM	`true`	عرض أصلي؛ استخدم `false` لمسار PDF النصي القابل للبحث.
`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
};