عارض – Doconut الوثائق

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

المكتبة السابقة لـ .NET Standard كانت تعرض مُنشئًا عامًا يأخذ ذاكرة التخزين المؤقت، وموصل سياق HTTP، ومسار أو أكثر لتراخيص. هذا المُنشئ لم يعد موجودًا؛ فإن مخطط الخدمة يزود بهذه الاعتمادات.

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

OpenDocumentAsync

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

التحميل الزائد	متى يستخدم
`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

// فتح بسيط
string token = await viewer.OpenDocumentAsync(path);

// مع تكوين وإعدادات لكل تنسيق
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// من تحميل
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)

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

GetWorksheetNames

text

IReadOnlyList<string> GetWorksheetNames(string token)

يعيد أسماء أوراق العمل لجدول بيانات مفتوح، بترتيب المصنف، أو قائمة فارغة عندما لا يكون المستند المفتوح جدول بيانات.

يتم سرد أوراق العمل التي تم عرضها فقط: تُستبعد أوراق العمل المخفية والفارغة، وعند تقييد العرض بواسطة ExcelConfig.SheetNames تُظهر فقط تلك الأوراق. ورقة العمل ليست دائمًا صفحة واحدة — الكبيرة جدًا تُعرض عبر عدة صفحات. يطرح استثناء إذا كان الرمز غير معروف أو منتهي الصلاحية.

تمت الإضافة في 26.9.0.

أعلام القدرة

العضو	المعنى
`bool IsSearchEnabled`	الرخصة الحالية تمنح `Search`
`bool IsAnnotationEnabled`	الرخصة الحالية تمنح `Annotation`

استخدم هذه في عرض Razor لتصوير شريط مرخص فقط عندما يكون الخادم سيقدمه فعليًا — انظر البدء السريع.

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

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

النوع	الخاصية	القيمة الافتراضية	الوصف
`string`	`Password`	`""`	كلمة المرور للمستندات المحمية (تُنسخ تلقائيًا إلى إعدادات الصيغة).
`int`	`ImageResolution`	`0`	مهمل. يُحفظ للتوافق فقط — بدلاً من ذلك اضبط `ImageResolution` في إعدادات الصيغة.
`string`	`Watermark`	`""`	نص العلامة المائية المخصصة المرسوم على الصفحات المُعالجة. سلسلة التنسيق: `"^Text~Color~FontSize~FontName~Opacity~Angle"`، مثال: `"^Sample Copy~Red~24~Verdana~80~-45"`.
`int`	`TimeOut`	`60`	انتهاء صلاحية الجلسة المتحركة بالدقائق.
`bool`	`IsSecured`	`true`	غير مفروض حاليًا — محجوز. ربط الرموز يتم التحكم فيه عالميًا بواسطة `DoconutOptions.UnsafeMode` (انظر المفاهيم الأساسية → الجلسات والأمان).

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

النوع	الخاصية	القيمة الافتراضية	الوصف
`bool`	`IsWebFarm`	`false`	يُشير إلى أن عملية الفتح هي سيناريو تخزين مشترك. لاحظ حالة الأحرف — المكتبة السابقة كانت تكتب هذا كـ `IsWebfarm`.
`string`	`WebFarmPath`	`""`	المسار المشترك المستخدم في هذا سير العمل. كان يُكتب سابقًا كـ `WebfarmPath`. يكون فارغًا في عارض المضيف الواحد العادي، ولا يُحتاج إليه في مسار النشر الموضح في التوزيعات الموزعة.
`bool`	`EditMode`	`false`	محجوز لسير عمل تحرير موزع بشكل منفصل؛ اترك `false` للعارض القياسي.

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

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

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
    });

الحقل	مثال	المعنى
المقدمة `^`	`^`	تخطيط اختياري يغطي جميع الزوايا. بدونها يُستخدم وضع العلامة المائية العادي.
النص	`Confidential`	النص المعروض على كل صفحة. يجب ألا يكون فارغًا.
اللون	`Red`	لون مسمى يُفهمه طبقة الرسم.
حجم الخط	`24`	حجم الخط؛ إذا كان الإدخال الرقمي غير صالح يُرجع إلى الإعداد الافتراضي للعارض.
اسم الخط	`Verdana`	عائلة الخط المطلوبة. تأكد من تثبيتها في بيئة النشر.
الشفافية	`80`	قيمة بايت من 0 إلى 255. يجب أن تُ解析 بنجاح.
الزاوية	`-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 لكل صفحة مع تعليقات مضمنة

كل واحد من هؤلاء يتطلب رمز الجلسة. الشكل غير المرتبط بجلسة المكتبة السابقة GetAnnotationManager(pageWidth, pageHeight) لا يزال موجودًا لإنشاء التعليقات التوضيحية خارج جلسة، لكن تحميلها لا يزال يتطلب رمزًا.

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

text

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

الطريقة موجودة لتوافق واجهة البرمجة، لكن هذه الحزمة لا يمكنها توفير وسوم DICOM التقنية: قارئ البيانات الوصفية يوزع فقط نسخة .NET 8. يعيد null للجلسات DICOM وغير DICOM؛ في جلسة DICOM يكتب أيضًا تحذيرًا لمرة واحدة يشرح قيود المنصة. لا يزال دعم عرض الصفحات والإطارات والرسوم المتحركة متاحًا.

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

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

text

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + عارض + بحث + تعليق
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 }))

هذه المساعدات هي الطريقة المدعومة لتوفير موارد المتصفح. يجب على التطبيقات التي نسخت docViewer.js و documentLinks.js و docViewer.UI.js إلى wwwroot إزالة تلك النسخ بمجرد أن تُظهر الصفحة من الوسوم المُصدرة.