إعدادات الصيغ – Doconut الوثائق

يفتح كل مستند باستخدام تنفيذ BaseConfig. مرّر واحدًا إلى OpenDocumentAsync أو دع كتالوج الصيغ ينشئ الافتراضي. جميع الفئات أدناه موجودة في مساحة الاسم Doconut.

مساحة الاسم الوحيدة هذه جديدة. مكتبة .NET Standard السابقة وزعت هذه الأنواع عبر Doconut.Configs و Doconut.Configs.View و Doconut.Models. أسماء الأنواع لم تتغير — في معظم الملفات التعديل الكامل هو حذف سطرين من using. راجع دليل الترحيل.

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

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`	فارغ	تقييد العرض إلى أوراق العمل المسماة.
`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`.

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

الصيغ: 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`	فرض أبعاد صفحة ثابتة.

تكوين الصورة، 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` يعني غير محدود؛ القيم غير الصفرية أقل من 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 // العودة إلى الإعداد الافتراضي للتنسيق
};