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

بين 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 إلى التكوين للمستندات المحمية.

المرحلة 1b — وضع التحويل (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

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

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

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

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

أين تُضبط ماذا