تكوينات الصيغ – 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

النوع	الخاصية	الافتراضي	السلوك
`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`	عدد النقاط في البوصة المستهدف للصور التي تم تغيير حجمها.
`bool`	`CompressFast`	`false`	تفضيل مسار الضغط الأسرع والأقل جودة.
`bool`	`FixInvalidImages`	`false`	محاولة إصلاح الصور المدمجة غير الصالحة.
`bool`	`SplitSegments`	`false`	إعادة ربط الكلمات المقسمة عبر مقاطع السطر لتحسين البحث/النسخ.

showHyperlinks في ViewerConfig يتحكم في تراكب العميل، بينما ExtractHyperlinks يتحكم في استخراج الخادم. فعّل كلاهما.

WordConfig

النوع	الخاصية	الافتراضي	السلوك
`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

النوع	الخاصية	الافتراضي	السلوك
`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، جميعها سلاسل قابلة للnull.

new ExcelConfig() يضبط SplitWorksheets إلى false؛ فتح ملف Excel دون تكوين صريح يستخدم كتالوج الصيغ، الذي يضبطه إلى true.

PptConfig

النوع	الخاصية	الافتراضي	السلوك
`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`.

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

CadConfig

النوع	الخاصية	الافتراضي	السلوك
`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

النوع	الخاصية	الافتراضي	السلوك
`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, 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

النوع	الخاصية	الافتراضي	السلوك
`int`	`HorizontalResolution`	`100` effective	DPI أفقي صريح؛ وإلا يستخدم `ImageResolution`، ثم 100.
`int`	`VerticalResolution`	`100` effective	DPI عمودي صريح؛ وإلا يستخدم `ImageResolution`، ثم 100.
`int`	`AnimationFrameDelayMs`	`100`	تأخير الإطار المتعدد في الرسوم المتحركة؛ توقيت GIF يستخدم وحدات 10 مللي ثانية.
`ushort`	`LoopCount`	`0`	`0` يعني تكرار إلى الأبد؛ القيم الموجبة تتوقف بعد عدد التكرارات المحدد.
`DicomDisplayMode`	`DisplayMode`	`AnimationAndFrames`	`AnimationOnly`، `FramesOnly`، أو نظرة عامة مدمجة مع إطارات ثابتة.

TxtConfig

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

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

ProjectConfig

النوع	الخاصية	الافتراضي	السلوك
`bool`	`DefaultRender`	`true`	صورة Gantt الأصلية؛ `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

النوع	الخاصية	الافتراضي	السلوك
`bool`	`DefaultRender`	`true`	عرض المخطط الأصلي؛ `false` يستخدم التحويل إلى PDF.
`PdfConfig`	`PdfConfig`	new instance	إعدادات مسار 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` on the class; `false` in the automatic catalog	true على الفئة؛ false في الكتالوج التلقائي
`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
};