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

Viewer (namespace Doconut) هو نقطة الدخول العامة لفتح المستندات من وحدات تحكم MVC، صفحات Web Forms، والمعالجات. إنها خدمة مؤقتة يتم تكوينها بواسطة DoconutHost.Initialize؛ احصل عليها حيث تستخدمها:

csharp

var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() يعمل أيضًا بمجرد تشغيل DoconutHost.Initialize — فهو يحل نفس الخدمات — مما يحافظ على تجميع الكود المهاجر من الحزمة الكلاسيكية. قبل Initialize، يطرح InvalidOperationException.

Viewer لا يحتفظ بحالة مستند حسب الطلب ويتعمد عدم تنفيذ IDisposable: جلسات المستند تعيش بشكل مستقل عنه، لذا فإن التخلص من Viewer لا يمكن أن يغلق مستندًا مفتوحًا أبداً (انظر كيف يعمل العارض).

OpenDocumentAsync

يفتح مستندًا ويعيد رمز الجلسة الذي يستخدمه الودجت في كل طلب لاحق. عندما تكون UnsafeMode false (الإعداد الافتراضي)، يُمنح الرمز إلى جلسة ASP.NET للطلب الحالي — استدعِه من طلب يحتوي على حالة جلسة (انظر الجلسات والأمان).

التحميل الزائد	متى يستخدم
`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 (HttpPostedFileBase in MVC; HttpPostedFile in Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

الاستثناءات التي يجب التعامل معها:

LicenseException — تم العثور على ترخيص لكنه رُفض (الرسالة تحمل السبب)، أو أن التنسيق يحتاج إلى قدرة مكوّن إضافي لا يمنحها الترخيص.
FormatNotSupportedException — لا يوجد عارض يتعامل مع امتداد الملف.
InvalidDataException — المحتوى تالف أو لا يتطابق مع امتداده.

OpenDocument (متزامن)

لـ code-behind في Web Forms وغيرها من الأكواد التي لا تستخدم الصفحات غير المتزامنة:

text

string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

كل منها يعيد الرمز ويخزنه أيضًا في viewer.Token. يجب أن يحمل fileName الامتداد الصحيح. هذه الأغطية آمنة للاستدعاء من صفحة Web Forms: مسار الفتح لا يستأنف أبدًا على سياق طلب ASP.NET، لذا الانتظار عليه لا يمكن أن يسبب تجمّداً. وهذا ليس صحيحًا بالنسبة لكل واجهة برمجة تطبيقات Doconut غير المتزامنة — انظر قسم Web Forms في ملحق المحول.

إغلاق المستند

text

void CloseDocument(string token)

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

استعلامات الجلسة

العضو	الإرجاع
`int GetPageCount(string token)`	إجمالي صفحات المستند المفتوح
`(int Width, int Height) GetPageDimensions(string token, int page = 1)`	حجم الصفحة المُعرض افتراضياً عند تكبير 100 % — مساحة الإحداثيات للتعليقات التوضيحية المدمجة في الشيفرة
`IReadOnlyList<string> GetWorksheetNames(string token)`	أوراق العمل المعروضة لملف جدول البيانات، بترتيب دفتر العمل؛ فارغ للوثائق الأخرى

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

DocOptions

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

النوع	الخاصية	الافتراضي	الوصف
`string`	`Password`	`""`	كلمة المرور للمستندات المحمية (تُنسخ تلقائياً إلى تكوين التنسيق).
`string`	`Watermark`	`""`	نص علامة مائية مخصص يُرسم على الصفحات المُعرضة — انظر أدناه.
`int`	`TimeOut`	`60`	انتهاء صلاحية الجلسة المتحرك، بالدقائق.
`string`	`BrowserId`	`""`	مزارع الويب: المتصفح المرتبط بتذكرة موقعة. عيّنها باستخدام `DoconutFarmBinding.EnsureBrowserId` (انظر Sessions & Security).
`string`	`UserId`	`""`	مزارع الويب: المستخدم المُسجَّل المرتبط بالتذكرة، من `DoconutFarmBinding.ResolveUserId`.
`int`	`ImageResolution`	`0`	مهمل. عيّن `ImageResolution` في تكوين التنسيق بدلاً من ذلك.
`bool`	`IsSecured`	`true`	محجوز؛ غير مفروض. التحكم في الوصول هو `DoconutOptions.UnsafeMode`.
`bool`	`IsWebFarm` / `string` `WebFarmPath`	`false` / `""`	محفوظ للشفرة التي تم ترحيلها من الحزمة الكلاسيكية. لا يبدّل وضع المزرعة — `AddDoconutDistributed` هو المسؤول.
`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
    });

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

المحلل يتوقع بالضبط ستة حقول بعد المقدمة الاختيارية ^. إذا كان التعريف غير صالح يُستبدل بنص علامة مائية Invalid Watermark مرئي بدلاً من الاختفاء الصامت.

قرار الترخيص

حالة الترخيص	القيمة المخصصة المقدَّمة	النتيجة المعروضة
ترخيص عارض مدفوع صالح	لا	صفحة نظيفة
ترخيص عارض مدفوع صالح	نعم	علامة مائية مخصصة
ترخيص تجريبي/مؤقت نشط	لا	صفحة نظيفة
ترخيص تجريبي/مؤقت نشط	نعم	علامة مائية مخصصة
ترخيص مفقود، مرفوض، منتهي، نسخة غير صحيحة، أو نطاق غير صالح	أيًا كان	علامة مائية تقييم؛ القيمة المخصصة لا تستبدلها

ينطبق نفس القرار على الصفحات المقدَّمة وعلى تصدير التعليقات التوضيحية. العلامة المائية المخصصة هي ميزة لتطبيق مرخص، وليست وسيلة لاستبدال علامة مائية التقييم.

واجهة برمجة تطبيقات التعليقات التوضيحية

تحميل وتعريف التعليقات التوضيحية من جانب الخادم وتصديرها. الشرح التفصيلي موجود في التعليقات التوضيحية.

العضو	الغرض
`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)`	تحميل الغلاف المشفر الذي تُعيده `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

text

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

في هذه الحزمة دائمًا تُعيد null، وتُجيب طلب بيانات تعريف الواجهة بـ 501 Not Implemented: قراءة وسوم DICOM غير متاحة على .NET Framework. DICOM العرض — الصفحات، الإطارات، والرسوم المتحركة — يعمل. انظر ملحق DICOM.

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

أصدر وسوم <link> و <script> للموارد التي يقدمها وحدة الموارد تحت DoconutOptions.ResourcesPath، بترتيب الاعتماد. تُصدر الملفات الخاصة بالميزات المقيدة بالترخيص (Search, Annotation) فقط عندما يمنح الترخيص إياها.

text

string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // license state, for guarding ribbon init code
bool IsAnnotationEnabled { get; }

علامات CssConfig: IncludeBootstrapCss، IncludeViewerCss، IncludeSearchCss (مقيد بالبحث)، IncludeAnnotationCss (مقيد بالتعليق).

علامات ScriptConfig: IncludeJQuery (مطلوب من قبل جميع الآخرين)، IncludeBootstrap، IncludeViewerScripts (سكريبتات العارض الأساسية)، IncludeSearchScripts و IncludeSearchBar (مقيد بالبحث)، IncludeAnnotationScripts و IncludeAnnotationBar (مقيد بالتعليق).

كلاهما يُعيد HTML: اكتبهما باستخدام @Html.Raw(...) في MVC 5 (أنشئهما في المتحكم — لا تحتوي العروض على @inject) أو <%= %> في Web Forms. البدء السريع يوضح كلاهما.

عرض العارض

text

string RenderViewer(string elementId, string token, ViewerConfig? config = null)

تُعيد كتلة <script> تُهيئ الواجهة على العنصر الذي يحمل المعرف elementId وتعرض المستند: docViewer({...}) المُنشأة من ViewerConfig (الإعداد الافتراضي: BasePath: '/'، ResPath: 'doconut-res/images')، ثم .View(token). اكتبها بعد سكريبتات العارض. لا يحتفظ السكريبت المُولد بأي إشارة إلى كائن العارض، لذا يجب على صفحة تحتوي على شريط أدوات خاص بها أن تُهيئ الواجهة يدويًا بدلاً من ذلك. انظر إعدادات العارض.

مزرعة الويب

string? AccessToken يحتوي على التذكرة الموقعة التي أصدرها أحدث فتح عندما يكون الوضع الموزع نشطًا وUnsafeMode يساوي false؛ تكون قيمتها null على خادم واحد. أرسلها إلى الواجهة مع الرمز: objViewer.View(token, access).