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

الصيغة: 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` on the class; `false` in the automatic catalog	الفتح العادي بدون إعداد يستخدم إعادة توجيه 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 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
};