عارض

الفئة الرئيسية لعرض المستند

Viewer (المساحة Doconut) هو نقطة الدخول العامة لفتح المستندات من صفحات Razor، وحدات تحكم MVC، مكوّنات Blazor، أو واجهات برمجة تطبيقات بسيطة. إنه مغلق، مسجَّل كخدمة متنقلة بواسطة AddDoconut()، ويتم حله عبر حقن الباني — لا تقم بإنشائه مباشرةً.

Viewer لا يحتفظ بأي حالة لكل طلب ويقصد عدم ليس تنفيذ IDisposable: جلسات المستند تعيش بشكل مستقل في ذاكرة التخزين المؤقت للجلسة، لذا لا يمكن لتدمير الخدمة أن يغلق مستندًا مفتوحًا (انظر المفاهيم الأساسية → كيف يعمل العارض).

OpenDocumentAsync – فتح المستند بشكل غير متزامن

يفتح مستندًا ويعيد رمز الجلسة الذي يستخدمه عنصر واجهة العميل لجميع الطلبات اللاحقة.

التحميل الزائدمتى يستخدم
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)فتح من القرص مع اكتشاف الصيغة تلقائيًا واستخدام الإعدادات الافتراضية للصيغة
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)تحتاج إلى خيارات عرض مخصصة لكل صيغة (PdfConfig، WordConfig، …)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)المستند ليس ملفًا على القرص (رفع، قاعدة بيانات، blob). يجب أن يحمل fileInfo الامتداد الصحيح — وهو ما يحدد الصيغة
csharp
// Simple open
string token = await viewer.OpenDocumentAsync(path);

// With per-format config and options
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// From an upload
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

الاستثناءات التي يجب التعامل معها:

  • LicenseException — تم رفض الترخيص الموجود (تحمل الرسالة سبب الرفض)، أو أن الصيغة تحتاج إلى قدرة مكوّن إضافي لم تعد مُمنوحة. انتهاء صلاحية التقويم دون رسالة رفض يتحول إلى عرض مائي بدلاً من إلقاء استثناء.
  • FormatNotSupportedException — Document format '<extension>' is not supported. (صيغة المستند '' غير مدعومة.)
  • InvalidDataException — محتوى الملف تالف أو لا يتطابق مع امتداده.

CloseDocument – إغلاق المستند

text
void CloseDocument(string token)

يزيل الجلسة من الذاكرة المؤقتة (يُدمّر محرك المستند فورًا)، يحذف علامة الأمان، ويسحب منح الوصول. اختياري — انتهاء الصلاحية المتحرك يقوم بنفس عملية التنظيف — لكنه يُنصح به للمستندات الكبيرة.

GetPageCount – الحصول على عدد الصفحات

text
int GetPageCount(string token)

إجمالي صفحات الجلسة المفتوحة. يطرح استثناء إذا كان الرمز غير معروف أو منتهي الصلاحية.

DocOptions – خيارات المستند

خيارات مستقلة عن الصيغة لكل فتح (المساحة Doconut):

النوعالخاصيةالقيمة الافتراضيةالوصف
stringPassword""كلمة المرور للمستندات المحمية (تُنسخ تلقائيًا إلى تكوين الصيغة).
intImageResolution0مهمل. محفوظ للتوافق فقط — اضبط ImageResolution في تكوين الصيغة بدلاً من ذلك.
stringWatermark""نص علامة مائية مخصص يُرسم على الصفحات المُعالجة. سلسلة التنسيق: "^Text~Color~FontSize~FontName~Opacity~Angle"، مثال: "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60انتهاء صلاحية الجلسة المتحرك بالدقائق.
boolIsSecuredtrueغير مفعل حاليًا — محجوز. ربط الرمز يتم التحكم فيه عالميًا عبر DoconutOptions.UnsafeMode (انظر المفاهيم الأساسية → الجلسات والأمان).

تُظهر الفئة أيضًا خصائص متخصصة خارج تدفق العرض العادي لمضيف واحد عن قصد:

النوعالخاصيةالقيمة الافتراضيةالوصف
boolIsWebFarmfalseيُشير إلى أن عملية الفتح هي سيناريو مزرعة ويب. استخدمه فقط مع بنية التخزين/الجلسة المشتركة المقابلة.
stringWebFarmPath""المسار المشترك المُستخدم في سير عمل مزرعة الويب المتخصص. يكون فارغًا في عارض المضيف الواحد العادي.
boolEditModefalseمحجوز لسير عمل المحرر الموزع منفصلًا؛ اتركه false للعارض القياسي.

علامة مائية مخصصة

DocOptions.Watermark يستخدم ستة حقول مفصولة بالـ tilde. يطلب ^ الاختياري في البداية تخطيطًا يغطي جميع الزوايا:

text
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
الحقلمثالالمعنى
Leading ^^تخطيط اختياري يغطي جميع الزوايا. بدونها، يُستخدم وضع العلامة المائية العادي.
TextConfidentialالنص المُرسم على كل صفحة. يجب ألا يكون فارغًا.
ColorRedلون مسمى يُفهمه طبقة الرسم.
FontSize24حجم الخط؛ إذا كان الإدخال الرقمي غير صالح يُرجع إلى الإعداد الافتراضي للمعالج.
FontNameVerdanaعائلة الخط المطلوبة. تأكد من تثبيتها في بيئة النشر.
Opacity80قيمة بايت من 0 إلى 255. يجب أن تُ解析 بنجاح.
Angle-45زاوية الدوران بالدرجات؛ إذا كان الإدخال الرقمي غير صالح يُرجع إلى القيمة الافتراضية.

المحلل يتوقع بالضبط ستة حقول بعد ^ الاختياري. إذا كان التعريف غير صالح يتم استبداله بـ Invalid Watermark الظاهر في SDK بدلاً من الاختفاء صامتًا.

قرار الترخيص

حالة الترخيصالقيمة المخصصة المقدمةالنتيجة المعروضة
ترخيص عارض مدفوع صالحلاصفحة نظيفة
ترخيص عارض مدفوع صالحنعمعلامة مائية مخصصة
عارض أساسي تجريبي/مؤقت نشطلاصفحة عارض أساسية نظيفة
عارض أساسي تجريبي/مؤقت نشطنعمعلامة مائية مخصصة عندما ينطبق مسار العارض الأساسي النظيف
ترخيص مفقود أو مرفوض أو منتهي أو نسخة غير صحيحة أو نطاق غير صالحأيًا كانعلامة مائية للإنفاذ/التقييم؛ القيمة المخصصة لا تتجاوزها
عرض المكوّن الإضافي وفقًا لقواعد التقييمأيًا كانعلامة مائية للتقييم

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

واجهة برمجة تطبيقات التعليقات التوضيحية

تحميل وتعريف التعليقات التوضيحية من جانب الخادم وتصديرها. الدليل الكامل موجود في الأدلة → التعليقات التوضيحية؛ الواجهة هي:

العضوالغرض
AnnotationManager GetAnnotationManager(string token)مدير مرتبط بأبعاد صفحات الجلسة المفتوحة
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)مدير بأبعاد صفحة صريحة
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)مدير مستقل عن الجلسة
void LoadAnnotationData(string token, AnnotationManager manager)تحميل التعليقات التوضيحية المبنية بـ C# إلى الجلسة
void LoadAnnotationData(string token, string annotationData)تحميل التعليقات التوضيحية من الغلاف المشفر للصفحة/Base64 الذي تُعيده AnnotationManager.GetAnnotationData()
void LoadAnnotationXML(string token, XmlDocument annotationXml)تحميل التعليقات التوضيحية من XML
XmlDocument GetAnnotationXML(string token)تصدير تعليقات الجلسة كملف XML
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)PDF مع تعليقات مدمجة
Task<int> ExportAnnotationsToPngAsync(…)ملفات PNG مع تعليقات مدمجة
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)ملف ZIP يحتوي على PNG لكل صفحة مع تعليقات مدمجة

بيانات تعريف DICOM

text
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

يعيد بيانات تعريف علامات DICOM للجلسات المفتوحة عبر مكوّن DICOM الإضافي؛ null للمستندات غير DICOM.

مساعدي الموارد — ReferenceCss / ReferenceScripts

يُصدر وسوم <link>/<script> للموارد المدمجة التي تُقدمها UseDoconutResources()، بترتيب الاعتماد الصحيح. تُصدر الحزم للميزات المقيدة بالترخيص مثل البحث والتعليقات التوضيحية فقط عندما يُفعل الترخيص هذه الميزات، مما يحافظ على توافق واجهة المستخدم للعميل مع سلوك الخادم.

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

علامات CssConfig: IncludeBootstrapCss، IncludeViewerCss، IncludeSearchCss (مقيد بالبحث)، IncludeAnnotationCss (مقيد بالتعليقات).

علامات ScriptConfig: IncludeJQuery (مطلوب من جميع الآخرين)، IncludeBootstrap، IncludeViewerScripts (الأساسي: docViewer.js + مقسم + روابط)، IncludeSearchScripts و IncludeSearchBar (مقيد بالبحث)، IncludeAnnotationScripts و IncludeAnnotationBar (مقيد بالتعليقات).

html
@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

هل كانت هذه الصفحة مفيدة؟