كيفية إنشاء معاينة في .NET باستخدام GroupDocs.Annotation

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

إجابات سريعة

فئة AnnotationApi هي المكوّن الأساسي في GroupDocs.Annotation الذي يحمل المستندات وينشئ صور المعاينة. طريقة GetPages تُعيد صور الصفحات المُصوَّرة كمصفوفات بايت. علم HideAnnotations يزيل جميع طبقات التعليقات التوضيحية من الصورة المُصوَّرة.

  • ما هي أسرع طريقة لعرض صورة مصغرة لملف PDF؟ حمّل ملف PDF باستخدام AnnotationApi، عيّن DPI = 150، واستدعِ GetPages – تُعيد الصفحة الأولى كملف PNG في أقل من 200 ms لملف حجمه 2 MB.
  • هل يمكنني إخفاء جميع التعليقات التوضيحية في المعاينة؟ نعم – استخدم علم HideAnnotations قبل العرض لإنتاج رؤية نظيفة.
  • هل توليد المعاينة آمن من حيث الخيوط (thread‑safe)؟ الـ API لا يحمل حالة؛ يمكنك تشغيل مهام معاينة متعددة بالتوازي بأمان.
  • هل أحتاج إلى ترخيص للاستخدام في الإنتاج؟ يلزم وجود ترخيص صالح لـ GroupDocs.Annotation لتوليد معاينات غير محدودة.
  • ما إصدارات .NET المدعومة؟ .NET Framework 4.6+، .NET Core 3.1+، .NET 5/6/7.

ما هي معاينة المستند؟

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

لماذا تستخدم معاينة المستند الآمنة؟

تضمن معاينة المستند الآمنة أن البيانات الوصفية الحساسة، الطبقات المخفية، أو التعليقات التوضيحية المقيدة لا تخرج من الخادم. تقوم GroupDocs.Annotation بتشفير تدفق المعاينة وإزالة أي علامات لا تسمح بها صراحةً، مما يمنحك سيطرة كاملة على ما يراه المستخدمون النهائيون. ادعاء مُقنَّى: المكتبة تدعم 30+ تنسيق ملف ويمكنها توليد معاينات لـ 500‑صفحة PDF في أقل من ثانيتين على خادم قياسي بثمانية أنوية عند استخدام DPI الافتراضي 150.

كيف تقوم بإنشاء صورة مصغرة لملف PDF؟

حمّل ملف PDF باستخدام AnnotationApi، حدّد DPI يتراوح بين 150‑300 للحصول على نص واضح، واطلب الصفحة الأولى كملف PNG. تُعيد هذه العملية ذات الخطوتين مصفوفة بايت يمكنك بثها مباشرة إلى المتصفح أو تخزينها على القرص. استخدام DPI أعلى (مثل 300) يحسّن قابلية القراءة للمستندات النصية الكثيفة، بينما DPI أقل (مثل 72) يقلل حجم الملف لشبكات الصور المصغرة.

المتطلبات المسبقة

  • .NET Framework 4.6+ أو .NET Core 3.1+ مثبتة.
  • ترخيص صالح لـ GroupDocs.Annotation (الترخيص المؤقت يعمل للتقييم).
  • الوصول إلى ملفات PDF أو Word أو Excel أو أي ملفات مدعومة أخرى تريد معاينتها.

كيفية إنشاء معاينة خطوة بخطوة

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

الخطوة 1: تثبيت حزمة NuGet

افتح وحدة التحكم الخاصة بـ Package Manager في مشروعك وشغّل:

Install-Package GroupDocs.Annotation

الخطوة 2: تهيئة الـ API

أنشئ مثيلًا من AnnotationApi، مع تمرير مسار ملف الترخيص وإعدادات اختيارية (مثل مجلد التخزين المؤقت، حد الذاكرة).

var config = new AnnotationConfig
{
    LicensePath = "GroupDocs.Annotation.lic",
    CacheFolder = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Cache")
};
var annotationApi = new AnnotationApi(config);

الخطوة 3: إنشاء معاينة بدون تعليقات توضيحية

عيّن علم HideAnnotations إلى true، اختر DPI المطلوب، واطلب الصفحات التي تحتاجها.

var previewOptions = new PreviewOptions
{
    HideAnnotations = true,
    Dpi = 150,
    OutputFormat = PreviewOutputFormat.Png,
    PageNumbers = new[] { 1 }   // first page only for thumbnail
};

byte[] previewBytes = annotationApi.GetPreview("sample.pdf", previewOptions);
File.WriteAllBytes("sample_thumb.png", previewBytes);

استدعاء GetPreview يُعيد مصفوفة بايت يمكنك إرسالها مباشرةً كاستجابة HTTP، تخزينها في CDN، أو تضمينها في مكوّن واجهة المستخدم.

الخطوة 4: تخزين المؤقت وإعادة استخدام المعاينات

لتجنب إعادة توليد نفس المعاينة مرارًا، احفظ الصورة باستخدام تجزئة (hash) من الملف المصدر وإعدادات المعاينة كمفتاح تخزين مؤقت. عندما يتغيّر المستند الأصلي، قم بإبطال التخزين المؤقت بمقارنة الطوابع الزمنية.

string cacheKey = $"{Path.GetFileNameWithoutExtension(filePath)}_{previewOptions.Dpi}_{previewOptions.HideAnnotations}";

الخطوة 5: التعامل مع المستندات الكبيرة بكفاءة

للملفات التي يزيد حجمها عن 100 MB، استخدم كتلة using لضمان أن AnnotationApi يتخلص من التدفقات الداخلية بسرعة. عالج الصفحات على دفعات إذا كنت تحتاج إلى معاينات متعددة الصفحات، وأفرغ كل دفعة قبل الانتقال إلى التالية.

سيناريوهات التنفيذ الشائعة

  • أنظمة إدارة المستندات – عرض شبكة من الصور المصغرة للتنقل البصري السريع.
  • منصات التعاون – عرض معاينات فقط للمراجعين، ثم السماح بتفعيل طبقات التعليقات عند الحاجة.
  • بوابات الويب – إظهار معاينة عند التحويم فوق روابط الملفات، لتقليل الحاجة إلى تنزيل كامل.
  • التطبيقات المحمولة – توليد PNG منخفض الدقة (72 DPI) للحفاظ على استهلاك النطاق الترددي تحت 50 KB لكل صفحة.

استكشاف أخطاء إنشاء المعاينة وإصلاحها

  • ارتفاع استهلاك الذاكرة مع ملفات PDF الكبيرة – تأكد من استدعاء Dispose() على AnnotationApi بعد كل دفعة معاينة، وحدّ عدد مهام المعاينة المتزامنة.
  • نص غير واضح في الصور المصغرة – زد DPI إلى 300 أو غيّر صيغة الإخراج إلى PNG؛ ضغط JPEG قد يطمس الأحرف الرفيعة.
  • غياب الصور في معاينات Excel – تأكد من تحميل كائنات المخططات بالكامل عبر ضبط LoadCharts = true في خيارات المعاينة.
  • بطء الاستجابة – انقل توليد المعاينة إلى عامل خلفية (مثل Task.Run) واعرض صورة بديلة حتى تصبح المعاينة الفعلية جاهزة.

الأسئلة المتكررة

س: هل يمكنني توليد معاينات للمستندات المحمية بكلمة مرور؟
ج: نعم. قدّم كلمة المرور في LoadOptions عند إنشاء مثيل AnnotationApi؛ سيتم توليد المعاينة بعد فك التشفير بنجاح.

س: هل تدعم المكتبة توليد معاينات لتنسيقات غير PDF مثل DOCX أو XLSX؟
ج: بالتأكيد. يمكن لـ GroupDocs.Annotation توليد معاينات لأكثر من 30 تنسيق مختلف، بما في ذلك DOCX، XLSX، PPTX، والعديد من أنواع الصور.

س: كيف أضمن أن المعاينة لا تكشف عن البيانات الوصفية المخفية؟
ج: استخدم خيار HideMetadata في PreviewOptions؛ يقوم الـ API بإزالة جميع خصائص المستند قبل رسم الصورة.

س: هل من الآمن نشر نقطة النهاية للمعاينة علنًا؟
ج: يتم توليد تدفق المعاينة على الخادم ويمكن تسليمه عبر HTTPS. اجمعه مع مصادقة تعتمد على الرموز لتقييد الوصول للمستخدمين المصرح لهم فقط.

س: ما هي سياسة انتهاء صلاحية التخزين المؤقت الموصى بها؟
ج: خزن المعاينات طوال عمر نسخة المستند المصدر. عندما يتغيّر الطابع الزمني لآخر تعديل للمستند، أبطِل الصورة المخزنة مؤقتًا وأعد توليدها.

موارد إضافية

آخر تحديث: 2026-08-09
تم الاختبار مع: GroupDocs.Annotation 23.10 for .NET
المؤلف: GroupDocs

دروس ذات صلة