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

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

Viewer لا يحمل حالة per-request ويتعمد not تنفيذ IDisposable: جلسات المستند تعيش بشكل مستقل في ذاكرة التخزين المؤقت للجلسة، لذا لا يمكن لتخلص الخدمة من الموارد أن تُغلق مستندًا مفتوحًا (انظر Core Concepts → How the Viewer Works).

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

// فتح بسيط
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)

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

DocOptions

خيارات لكل فتح، مستقلة عن الصيغة (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` (انظر Core Concepts → Sessions & Security).

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

النوع	الخاصية	القيمة الافتراضية	الوصف
`bool`	`IsWebFarm`	`false`	يُشير إلى أن عملية الفتح هي سيناريو مزرعة ويب. استخدمه فقط مع بنية التخزين/الجلسة المشتركة المقابلة.
`string`	`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 يحتوي على PNGs لكل صفحة مع تعليقات مدمجة

بيانات 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 }))

GetWorksheetNames

text

IReadOnlyList<string> GetWorksheetNames(string token)

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

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