تهيئة الصيغ – 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. يتطلب قدرة ترخيص البحث للطلبات.
`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`	دليل خطوط إضافي، مفيد خصوصًا في Linux/الحاويات.
`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`	مثيل جديد	إعدادات مسار 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`	فارغ	قصر العرض على أوراق العمل المسماة.
`CustomStyleCell?`	`CustomStyles`	`null`	تجاوزات اختيارية لتنسيق التاريخ/العشري/الصحيح.
`bool`	`AllowSearch`	`false`	يفوض إلى `PdfConfig.AllowSearch`.
`bool`	`AllowCopy`	`false`	يفوض إلى `PdfConfig.AllowCopy`.

CustomStyleCell يكشف عن CustomStyleDateTime، CustomStyleNumberDecimal، وCustomStyleNumberInteger، جميعها سلاسل يمكن أن تكون فارغة.

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`	مثيل جديد	إعدادات سلوك PDF/البحث.
`string`	`FontInfo`	`""`	معلومات استبدال الخط.
`string[]?`	`FontFolders`	`null`	دليل خطوط إضافية.
`bool`	`AllowSearch`	`false`	يفوض إلى `PdfConfig.AllowSearch`.
`bool`	`AllowCopy`	`false`	يفوض إلى `PdfConfig.AllowCopy`.

على نظامي Linux و macOS، يتطلب عرض العروض التقديمية بالمحرك الحالي libgdiplus و System.Drawing.EnableUnixSupport=true. قم بتثبيت الخطوط المستخدمة في العرض التقديمي أو قدم FontFolders.

تكوين CAD

الصيغ: 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`.

تكوين البريد الإلكتروني

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

تكوين Dicom

الصيغ: 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`، أو نظرة عامة مركبة بالإضافة إلى إطارات ثابتة.

تكوين النص

الصيغة: TXT. DPI الافتراضي: 200.

النوع	الخاصية	الافتراضي	السلوك
`DocPaperSize`	`PaperSize`	`A4`	حجم ورق الإخراج.
`Encoding?`	`FileEncoding`	`null`	`null` يستخدم UTF-8.
`string`	`FontInformation`	`""`	معلومات الخط لعرض النص.

استخدم WordConfig عندما يحتاج النص العادي إلى سلوك تخطيط صفحة أغنى.

تكوين المشروع

الصيغ: 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.

تكوين 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`	عرض أصلي؛ استخدم `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 = 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 إعادة توجيه → بحث نصي أصلي بدقة البكسل
    ".HTML" or ".HTM" => new HtmlConfig { DefaultRender = false },
    ".EML" or ".EMLX" or ".MSG" => new EmailConfig { DefaultRender = false },
    _ => null // العودة إلى الإعداد الافتراضي للتنسيق
};