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

Viewer (namespace 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

// فتح بسيط
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` (انظر المفاهيم الأساسية → الجلسات والأمان).

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

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

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

text

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

الطريقة موجودة لتوافق واجهة البرمجة، لكن عارض DICOM على .NET 6 لا يمكنه توفير العلامات التقنية. يعيد null لجلسات DICOM وغير DICOM؛ في جلسة 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 }))

احصل على أسماء الأوراق

text

IReadOnlyList<string> GetWorksheetNames(string token)

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

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