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

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

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

OpenDocumentAsync

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

Overload	Use when
`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));

Exceptions to handle:

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

CloseDocument

text

void CloseDocument(string token)

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

GetPageCount

text

int GetPageCount(string token)

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

DocOptions

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

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

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

Type	Property	Default	Description
`bool`	`IsWebFarm`	`false`	يحدد عملية الفتح كسيناريو مزرعة ويب. استخدمه فقط مع بنية التخزين/الجلسة المشتركة المقابلة.
`string`	`WebFarmPath`	`""`	المسار المشترك المستخدم في سير عمل مزرعة الويب المتخصص. يكون فارغًا في عارض المضيف الفردي العادي.
`bool`	`EditMode`	`false`	محجوز لسير عمل المحرر الموزع منفصلًا؛ اتركه `false` للعارض القياسي.

Custom watermark

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

Field	Example	Meaning
Leading `^`	`^`	تخطيط يغطي جميع الزوايا اختياريًا. بدونها يُستخدم وضع العلامة المائية العادي.
Text	`Confidential`	النص المرسوم على كل صفحة. يجب ألا يكون فارغًا.
Color	`Red`	لون مسمى يُفهم من قبل طبقة الرسم.
FontSize	`24`	حجم الخط؛ إذا كان الإدخال الرقمي غير صالح يُرجع إلى الإعداد الافتراضي للعارض.
FontName	`Verdana`	عائلة الخط المطلوبة. تأكد من تثبيتها في بيئة النشر.
Opacity	`80`	قيمة بايت من 0 إلى 255. يجب أن تُفسَّر بنجاح.
Angle	`-45`	زاوية الدوران بالدرجات؛ إذا كان الإدخال الرقمي غير صالح يُرجع إلى القيمة الافتراضية.

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

License decision

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

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

Annotations API

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

Member	Purpose
`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 metadata

text

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

الطريقة موجودة لتوافق API، لكن عارض DICOM في .NET 6 لا يستطيع توفير العلامات التقنية. تُعيد null لجلسات DICOM وغير DICOM؛ في جلسة DICOM تُكتب تحذير مرة واحدة يوضح قيود المنصة. لا يزال عرض الصفحات والإطارات والرسوم المتحركة مدعومًا.

Resource helpers — ReferenceCss / ReferenceScripts

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

text

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

CssConfig flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).

ScriptConfig flags: IncludeJQuery (required by all others), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts and IncludeSearchBar (search-gated), IncludeAnnotationScripts and IncludeAnnotationBar (annotation-gated).

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