خط أنابيب العرض

بين OpenDocumentAsync وملف PNG الذي يصل إلى المتصفح هناك مرحلتان متميزتان: حل العارض (أي المحرك الذي يحمل المستند، يُحدد مرة واحدة عند الفتح) و معالجة الصفحة (ما يحدث لكل صورة صفحة عند كل طلب). معرفة كلاهما يوضح لماذا يتم عرض صيغة معينة بهذه الطريقة — وما الذي يفعله DefaultRender فعليًا.

المرحلة 1 — حل عارض الصيغة

يقوم المصنع بربط امتداد الملف بعارض عبر كتالوج الصيغ، مع ثلاثة مستويات من الأسبقية:

1. أولاً العارضات المخصصة. أي شيء قمت بتسجيله باستخدام DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) يتفوق على جميع العارضات المدمجة.
2. العارضات العائلية المدمجة. يقوم الكتالوج بربط كل امتداد قابل للعرض بعائلة عارض — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — كل منها يمتلك محول محرك خاص به. إذا كان هناك مكوّن إضافي مرخص يضيف عارضًا لنفس الامتداد، فإن عارض المكوّن الإضافي يحل محل المدمج. AddDoconut() يتحقق من صلاحيات المكوّن الإضافي المسجلة عند بدء التشغيل؛ fallback المصنع إلى العارض المدمج هو قاعدة تشغيلية دفاعية.
3. الصيغ التي تعتمد على المكوّن الإضافي فقط. بعض الامتدادات لا تمتلك عارضًا مدمجًا على الإطلاق — DICOM (.dcm) موجود فقط عبر مكوّن DICOM الإضافي. فتح أحدها بدون القدرة المطلوبة يطرح الاستثناء التالي:

LicenseException: This document type requires the 'Dicom' plugin license.

امتداد لا يدعي أي عارض يرفع الاستثناء التالي:

FormatNotSupportedException: Document format '<extension>' is not supported.

بعد الحل، يتم تثبيت الإعدادات: كائن الإعدادات الصريح إذا قمت بتمريره، وإلا الإعداد الافتراضي للصيغة من الكتالوج. يتم نسخ DocOptions.Password إلى الإعدادات للمستندات المحمية.

المرحلة 1ب — وضع التحويل (DefaultRender = false)

معظم إعدادات الصيغ تعرض علم DefaultRender. يختار بين مسارين مختلفين جوهريًا:

• DefaultRender = true — يتم عرض المستند أصليًا، مباشرة إلى صور الصفحات.
• DefaultRender = false — يتم أولاً تحويل المستند إلى PDF في الذاكرة، يتم تحرير محرك المصدر، ويتولى عارض PDF المهمة. يضمّن PDF المُنشأ نصًا حقيقيًا، لذا يحصل البحث النصي الكامل على تمييزات أصلية دقيقة بالبكسل؛ يفرض خط الأنابيب تشغيل AllowSearch و AllowCopy للـ PDF المحوَّل لأن التحويل غير مرئي للمستخدم.

يستخدم XPS والافتراضي في الكتالوج لـ MHT مسار التحويل. يمكن لإسقاط PDF أن يوفر بحثًا أصليًا لصيغ مثل HTML وMicrosoft Project. إذا كان PDF الناتج يحتوي على صور دون طبقة نصية، فإن العارض القياسي لا يستطيع البحث في تلك البكسلات.

استخدم وضع التحويل عندما تحتاج إلى إسقاط PDF يحمل نصًا — على حساب تحويل مبدئي عند فتح المستند.

المرحلة 2 — خط أنابيب صورة الصفحة

يتم معالجة الصفحات المُعرضة لكل طلب عبر تسلسل ثابت:

raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response

• Watermark — يُطبق بناءً على حالة الترخيص (ترخيص مفقود، مؤقت أو اشتراك منتهي الصلاحية، نطاق غير صالح، نسخة خاطئة) ومن DocOptions.Watermark للنص المخصص الخاص بك. تطبيق مرخص بشكل صحيح — أو ترخيص مؤقت نشط — بدون علامة مائية مخصصة يتخطى هذه الخطوة.
• Rotate/flip — حالة الصفحة التي يحددها المستخدم في الواجهة (90°/180°/270°، انعكاسات أفقية/عمودية) تُخزن في الجلسة وتُطبق في كل عرض لاحق لتلك الصفحة.
• Scale — تُنتج المصغرات ومستويات التكبير عن طريق تحجيم الصفحة المعروضة إلى الحجم المستهدف المطلوب؛ 0 يعني تقديمها بالحجم الأصلي.
• Annotation burn — تُرسم التعليقات التوضيحية المحفوظة على البت ماب بحيث تُظهرها الصادرات وصور الصفحات.
• Encoding — يتم ترميز النتيجة إلى PNG باستخدام تدفقات الذاكرة المشتركة وتُكتب مباشرةً إلى استجابة HTTP.

الأخطاء داخل الطبقة الوسيطة تُعاد كـ PNG error images (نص أحمر على خلفية بيضاء) بدلاً من صفحات خطأ HTTP، حتى تتمكن الواجهة من عرضها في منطقة الصفحة.

تخزين الصفحات مؤقتًا

BaseConfig.CachePages (القيمة الافتراضية true) يحتفظ بصور الصفحات المعروضة في الذاكرة طوال مدة جلسة المستند، لذا لا يتم إعادة عرض الصفحة عند زيارتها مرة أخرى. BaseConfig.ImageResolution (25–300 DPI، 0 = الافتراضي للصيغة) هو المفتاح الرئيسي للجودة/الذاكرة؛ الافتراضي لكل صيغة موثَّق في صفحة إعداداتها.

أين تضبط ماذا