عارض

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

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)المستند ليس ملفًا على القرص (تحميل، قاعدة بيانات، كتلة). يجب أن يحمل 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)

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

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

حجم الصفحة الافتراضي المعروض للمستند عند تكبير 100 % — مساحة الإحداثيات للتعليقات التوضيحية المدمجة في الشيفرة. يتم قبول page للتوافق؛ النتيجة هي الإعداد الافتراضي للمستند. يرمي InvalidOperationException (Document session not found. Please re-open document.) إذا كان الرمز غير معروف أو منتهي الصلاحية، وArgumentException إذا كان الرمز فارغًا.

GetWorksheetNames

text
IReadOnlyList<string> GetWorksheetNames(string token)

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

يتم سرد أوراق العمل المعروضة فقط: تُستبعد أوراق العمل المخفية والفارغة، وعند ExcelConfig.SheetNames يحد من العرض، تظهر فقط تلك الأوراق. ورقة العمل ليست دائمًا صفحة واحدة — الكبيرة جدًا تُعرض عبر عدة صفحات. يرمي InvalidOperationException (Document session not found. Please re-open document.) إذا كان الرمز غير معروف أو منتهي الصلاحية، وArgumentException إذا كان الرمز فارغًا.

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

أعلام القدرة

العضوالمعنى
bool IsSearchEnabledالرخصة الحالية تمنح Search
bool IsAnnotationEnabledالرخصة الحالية تمنح Annotation

استخدم هذه في عرض Razor لعرض شريط مرخص فقط عندما يقوم الخادم فعليًا بخدمته — انظر البدء السريع.

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

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

النوعالخاصيةالقيمة الافتراضيةالوصف
stringPassword""كلمة المرور للمستندات المحمية (تُنسخ تلقائيًا إلى تكوين التنسيق).
intImageResolution0مهمل. يُحفظ للتوافق فقط — اضبط ImageResolution في تكوين التنسيق بدلاً من ذلك.
stringWatermark""نص علامة مائية مخصصة يُرسم على الصفحات المُعالجة. سلسلة التنسيق: "^Text~Color~FontSize~FontName~Opacity~Angle"، مثال: "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60انتهاء صلاحية الجلسة المتحركة بالدقائق.
boolIsSecuredtrueغير مفروض حاليًا — محجوز. ربط الرمز يتم التحكم فيه عالميًا بواسطة DoconutOptions.UnsafeMode (انظر المفاهيم الأساسية → الجلسات والأمان).

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

النوعالخاصيةالقيمة الافتراضيةالوصف
boolIsWebFarmfalseمهمل — لا تأثير له. انشر المستند باستخدام DistributedDocumentPublisher.PublishAsync (أو IDistributedPublishQueue.EnqueueAsync) واضبط FileShareConfig.RootPath بدلاً من ذلك.
stringWebFarmPath""مهمل — لا تأثير له. استخدم FileShareConfig.RootPath بدلاً من ذلك.
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عائلة الخط المطلوبة. تأكد من تثبيتها في بيئة النشر.
الشفافية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(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)صورة PNG واحدة لكل صفحة، مع دمج التعليقات التوضيحية، تُكتب إلى directoryPath (يُنشأ إذا كان مفقودًا)؛ تُعيد عدد الصور المكتوبة
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)ملف ZIP يحتوي على صور PNG لكل صفحة مع دمج التعليقات التوضيحية

بيانات ميتا 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 + عارض + بحث + تعليق
string ReferenceScripts(ScriptConfig? config = null)

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

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

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

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