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

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

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

Viewer لا يحمل أي حالة حسب الطلب ويتعمد عدم تنفيذ 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)

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

أعلام القدرة

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

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

DocOptions

خيارات مستقلة عن الصيغة لكل فتح (مساحة الاسم 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 يستخدم ستة حقول مفصولة بعلامة 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
    });

الحقل	مثال	معنى
المقدمة `^`	`^`	تخطيط جميع الزوايا اختياري. بدون ذلك، يُستخدم وضع العلامة المائية العادي.
نص	`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 + splitter + links), 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 يجب إزالة تلك النسخ بمجرد أن تُظهر الصفحة الوسوم الصادرة.