عارض

الفئة الرئيسية لعرض المستندات

Viewer (المساحة الاسمية 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)المستند ليس ملفًا على القرص (تحميل، قاعدة بيانات، كائن ثنائي). يجب أن يحمل fileInfo الامتداد الصحيح — فهو يختار الصيغة
csharp
// فتح بسيط
string token = await viewer.OpenDocumentAsync(path);

// مع تكوين لكل تنسيق وخيارات
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// من تحميل (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 (متزامن)

لشفرة خلفية 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، لذا الانتظار عليه لا يمكن أن يسبب تجمّداً. نفس الشيء ليس صحيحًا لكل API غير متزامن من 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)الأوراق المعروضة لجدول البيانات، بترتيب دفتر العمل؛ فارغ للمستندات الأخرى

كل منها يرمي InvalidOperationException (Document session not found. Please re-open document.) إذا كان الرمز المميز غير معروف أو منتهي الصلاحية، وArgumentException لرمز مميز فارغ.

خيارات المستند

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

النوعالخاصيةالافتراضيالوصف
stringPassword""كلمة المرور للمستندات المحمية (تُنسخ تلقائياً إلى تكوين التنسيق).
stringWatermark""نص علامة مائية مخصصة يُرسم على الصفحات المعروضة — انظر أدناه.
intTimeOut60انتهاء صلاحية الجلسة المتحركة، بالدقائق.
stringBrowserId""مزارع الويب: المتصفح المرتبط بالتذكرة الموقعة. اضبطه باستخدام DoconutFarmBinding.EnsureBrowserId (انظر الجلسات والأمان).
stringUserId""مزارع الويب: المستخدم الموقع الذي ترتبط به التذكرة، من DoconutFarmBinding.ResolveUserId.
intImageResolution0مهمل. اضبط ImageResolution في تكوين التنسيق بدلاً من ذلك.
boolIsSecuredtrueمحجوز؛ غير مفروض. التحكم في الوصول هو DoconutOptions.UnsafeMode.
boolIsWebFarm / string WebFarmPathfalse / ""محفوظ للشفرة التي تم ترحيلها من الحزمة الكلاسيكية. لا تقوم بتفعيل وضع المزرعة — AddDoconutDistributed يفعل ذلك.
boolEditModefalseمحجوز للمحرر الموزع بشكل منفصل؛ اترك 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عائلة الخط. يجب أن تكون مثبتة على الخادم — خادم Windows يحتوي على خطوط أقل من سطح المكتب.
الشفافية80من 0 إلى 255. يجب أن يتم تحليلها.
الزاوية-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(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)صورة PNG واحدة لكل صفحة، مع دمج التعليقات التوضيحية، تُكتب إلى directoryPath (يُنشأ إذا كان مفقودًا)؛ تُعيد عدد الصور المكتوبة
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)ملف ZIP للـ PNGs لكل صفحة مع دمج التعليقات التوضيحية

بيانات تعريف 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 + عارض + بحث + تعليق
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // حالة الترخيص, لحماية كود تهيئة الشريط
bool IsAnnotationEnabled { get; }

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

علامات ScriptConfig: IncludeJQuery (مطلوبة من قبل جميع الآخرين)، IncludeBootstrap، IncludeViewerScripts (نصوص عارض الأساس)، IncludeSearchScripts و IncludeSearchBar (مقيدة بالبحث)، IncludeAnnotationScripts و IncludeAnnotationBar (مقيدة بالتعليق)، EmitFeatureFlags (الافتراضي true: يكتب أيضًا نصًا مضمنًا window.Doconut.features = { search, annotation, editor }؛ اضبطه إلى false تحت سياسة أمان المحتوى التي تحظر النصوص المضمنة).

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

RenderViewer

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, accessToken).

هل كانت هذه الصفحة مفيدة؟