دمج Doconut في تطبيق الويب الخاص بك: دليل عملي

عارض Doconut هو مكتبة .NET لعرض المستندات صُممت لتمكين تضمين ملفات PDF، Office، CAD، الصور، وغيرها من عائلات المستندات المدعومة داخل تطبيق. تكامل Doconut السليم لا يتعلق بالعثور على أقصر قطعة شفرة، بل باختيار حد واضح بين تطبيقك، العارض، والمتصفح.

مستندات Doconut تُظهر مسارات الإعداد المدعومة لأنواع مشاريع .NET المختلفة. استخدم الدليل الذي يتوافق مع الإصدار المثبت في تطبيقك، ثم عالج الصفحة المحيطة، وفحوصات الهوية، وسير عمل الوصول ككود تطبيق يملكه فريقك.

---

ابدأ بحدود التكامل

هناك ثلاث طرق شائعة لوضع معاينة مستند في منتج. يعتمد الاختيار الصحيح على من يملك التنقل، المصادقة، ودورة حياة العارض.

النمط	الأفضل	المقايضة الرئيسية
عرض التطبيق	صفحة .NET تعرض العارض بجانب عناصر التحكم في المنتج	تكامل وثيق، لكن دورة حياة الصفحة والعارض مرتبطة
إطار مضمّن مملوك للتطبيق	بوابة تحتاج إلى عزل بين واجهة المستخدم المضيفة ومسار المعاينة	حد واضح، لكن يجب تصميم التواصل صراحةً
مكوّن إطار عمل حول مسار الخادم	قشرة React أو Angular أو Vue مدعومة بتطبيق .NET	تكوين واجهة أمامية مألوف، مع المزيد من حالات دورة الحياة لإدارتها

نمط الإطار المضمّن لا يحتاج إلى الإشارة إلى عنوان URL عام للمستند. يمكنه الإشارة إلى مسار مُصادَق داخل تطبيقك. يمكن لهذا المسار التحقق من الوصول وعرض صفحة العارض دون كشف مسار التخزين للصفحة المضيفة.

بناء سطح معاينة ثابت ومتجاوب

لا تُعيد إنشاء ترميز العارض أو تهيئته من مقتطف مدونة توضيحي. Doconut تنشر الملفات، خطوات الوسيط، المساحات الاسمية، وإعداد العارض المناسب لكل خط .NET مدعوم. على سبيل المثال، يشرح دليل الإعداد الرسمي لـ .NET 6 أو أعلى وسائط الخادم، كائن العارض، خيارات المستند، تكوين العرض، والأصول المطلوبة للعميل.

استخدم تلك المواد ذات الإصدارات لإنشاء العارض، ثم امنح منطقة الاستضافة عرضًا وارتفاعًا ثابتين في تخطيطك. احجز مساحة كافية قبل التحميل حتى لا تقفز الصفحة المحيطة، واختبر شريط الأدوات والصفحة الأولى عند نقاط الانكسار الحقيقية التي يدعمها منتجك.

قبل الالتزام بتكوين معين، قارن ذلك مع العروض الحية لـ Doconut. تغطي العروض أنماط تكامل .NET والواجهة الأمامية المتعددة، بما في ذلك مثال إطار مضمّن مخصص، وتساعدك على تمييز المسار المدعوم رسميًا عن المقتطف الذي يبدو مقنعًا.

احتفظ بقرارات الوصول على الخادم

يجب ألا تقرر الصفحة المضيفة ما إذا كان المستخدم يمكنه عرض مستند. قبل عرض مسار المعاينة، يجب على التطبيق:

1. مصادقة الطلب.
2. تفويض المستخدم للمستند المطلوب والمستأجر.
3. حل المستند عبر معرف يتحكم به الخادم.
4. فتحه عبر العارض فقط بعد نجاح تلك الفحوصات.
5. إرجاع حالة "غير موجود" أو "ممنوع" عامة دون تسريب تفاصيل التخزين.

المعرف غير الشفاف يحسن نظافة عنوان URL، لكنه ليس تفويضًا. طبق نفس الفحوصات على طلبات الصفحة، المصغرات، البحث، التعليقات، التصدير، والطباعة التي تعرضها.

حدد كيفية تواصل المضيف والعارض

يمكن لعرض التطبيق استدعاء مكوناته مباشرة. يحتاج الإطار المضمّن إلى عقدة أضيق. عرّف فقط الأحداث التي يحتاجها المضيف فعليًا، مثل:

• جاهزية المعاينة
• فشل فتح المستند
• تغيير الصفحة الحالية
• انتهاء الجلسة
• طلب المستخدم إغلاق المعاينة

إذا استخدمت postMessage، تحقق من كل من event.origin وشكل الرسالة. لا تقبل أصولًا عامة في بيئة الإنتاج، ولا تمرر أبدًا بيانات اعتماد، مواقع تخزين، أو محتوى المستند الخام عبر الرسائل.

اعتبار قيود المتصفح كدفاع متعدد الطبقات

الإطار المضمّن ليس معزولًا تلقائيًا. يمكن لخاصية sandbox تقليل الصلاحيات، لكن قيمة صارمة جدًا قد تعطل سكريبتات العارض، التحميلات، أو سلوك نفس الأصل. ابدأ بأصغر مجموعة صلاحيات موثقة لتكاملك واختبرها مع سياسة أمان المحتوى الخاصة بك.

كما يجب مراجعة:

• frame-ancestors أو X-Frame-Options لمسار المعاينة
• frame-src للصفحة المضيفة
• سلوك ملفات تعريف الارتباط ذات الموقع نفسه إذا كان الإطار المضمّن يحتاج جلسة
• سياسة الإحالة للروابط التي تحتوي على معرفات توجيه
• رؤوس التخزين المؤقت للصفحات التي تعرض مواد حساسة

هذه الضوابط تعود إلى التطبيق والبنية التحتية المحيطة. لا يمكن لمكون العارض اختيار السياسة الصحيحة لتأجيرك ونموذج التهديد الخاص بك.

تصميم حالات التحميل، الأخطاء، وانتهاء الصلاحية

المستطيل الفارغ ليس رسالة خطأ مفيدة. قدم للصفحة المضيفة حالات صريحة لفشل التفويض، الإدخال غير المدعوم، الملفات التالفة، مهلات الوقت، وانتهاء الجلسات. حافظ على صياغة قابلة للتنفيذ دون كشف مسارات داخلية أو تفاصيل استثناء.

للمستندات الطويلة، احتفظ بحاوية العارض بينما تُحضّر الصفحة الأولى. إذا كان بإمكان المستخدمين تبديل المستندات دون مغادرة الصفحة، ألغِ الطلبات القديمة وأعد ضبط العنوان الظاهر، عدد الصفحات، والتركيز قبل تحميل العنصر التالي.

إمكانية الوصول وسلوك لوحة المفاتيح

امنح كل إطار مضمّن title مفيدًا. اجعل المعاينة قابلة للوصول عبر لوحة المفاتيح، وقدّم طريقة مرئية لإعادة التركيز إلى الصفحة المضيفة، ولا تحبس التركيز داخل طبقات مخصصة. إذا كان للعارض اختصارات لوحة مفاتيح خاصة به، وثّق التعارض مع الاختصارات المستخدمة في صَدَفة منتجك.

يمكن أن يقدم بديل قابل للوصول تحميلًا مُتحكمًا أو تمثيلًا بديلًا عندما تسمح قواعد عملك بذلك. لا تضف رابط ملف عام مجردًا كبديل.

قائمة تحقق عملية

قبل الإصدار، تحقق من مسار الطلب الكامل وليس فقط تحميل الصفحة الأولية:

• يستطيع مستخدم مخوّل فتح مستند مسموح.
• لا يستطيع مستخدم من مستأجر آخر إعادة استخدام عنوان URL للمعاينة.
• الطلبات المباشرة لنقاط النهاية المتعلقة بالعارض تتلقى نفس فحوصات التفويض.
• التحديث، التنقل إلى الخلف، وانتهاء الجلسة ينتج عنه حالات مفهومة.
• تظل المعاينة قابلة للاستخدام بأحجام عرض ونسب تكبير مدعومة.
• أخطاء وحدة تحكم المتصفح وطلبات الشبكة الفاشلة مرئية في المراقبة.
• سجلات التخزين والتطبيق لا تسجل أسرارًا أو عناوين URL كاملة للمستندات.

الخلاصة

أكثر تكامل Doconut قابلًا للصيانة هو ذلك الذي يمتلك عقدًا صغيرًا وصريحًا. دع Doconut يتولى دور عرض المستند وفقًا لتوثيق إصداراته، بينما يملك تطبيقك الهوية، التفويض، التوجيه، الاحتفاظ، سياسات المتصفح، وتعليقات المستخدم. عندما تكون مستعدًا لتقييم الأمثلة المعبأة محليًا، استخدم موارد تنزيل Doconut الرسمية بدلاً من نسخ الشيفرة من مقالة غير ذات صلة.