عارض
الفئة الرئيسية لعارض المستندات
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 الامتداد الصحيح — فهو يحدد الكشف عن الصيغة |
// فتح بسيط
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
void CloseDocument(string token)يزيل الجلسة من الذاكرة المؤقتة (يتم التخلص من محرك المستند فورًا)، يحذف علامة الأمان، ويلغي منح الوصول. هذا اختياري — انتهاء الصلاحية المتدرج يقوم بنفس عملية التنظيف — لكنه موصى به للمستندات الكبيرة.
GetPageCount
int GetPageCount(string token)إجمالي صفحات الجلسة المفتوحة. يرمي InvalidOperationException (Document session not found. Please re-open document.) إذا كان الرمز غير معروف أو منتهي الصلاحية، وArgumentException إذا كان الرمز فارغًا.
GetPageDimensions
(int Width, int Height) GetPageDimensions(string token, int page = 1)حجم الصفحة الافتراضي المعروض للمستند عند تكبير 100 % — مساحة الإحداثيات للتعليقات التوضيحية المدمجة في الشيفرة. يتم قبول page للتوافق؛ النتيجة هي الإعداد الافتراضي للمستند. يرمي InvalidOperationException (Document session not found. Please re-open document.) إذا كان الرمز غير معروف أو منتهي الصلاحية، وArgumentException إذا كان الرمز فارغًا.
GetWorksheetNames
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):
| النوع | الخاصية | القيمة الافتراضية | الوصف |
|---|---|---|---|
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 | مهمل — لا تأثير له. انشر المستند باستخدام DistributedDocumentPublisher.PublishAsync (أو IDistributedPublishQueue.EnqueueAsync) واضبط FileShareConfig.RootPath بدلاً من ذلك. |
string | WebFarmPath | "" | مهمل — لا تأثير له. استخدم FileShareConfig.RootPath بدلاً من ذلك. |
bool | EditMode | false | محجوز لتدفق عمل المحرر الموزع بشكل منفصل؛ اترك false للعارض القياسي. |
علامة مائية مخصصة
DocOptions.Watermark يستخدم ستة حقول مفصولة بالـ ~. طلب اختياري للـ ^ يطلب تخطيط جميع الزوايا:
^Text~Color~FontSize~FontName~Opacity~Anglestring 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
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)هذه الطريقة موجودة لتوافق واجهة البرمجة، لكن عارض DICOM الخاص بـ .NET 6 لا يمكنه توفير العلامات التقنية. تُعيد null لجلسات DICOM وغير DICOM؛ في جلسة DICOM يكتب أيضًا تحذيرًا لمرة واحدة يشرح قيود المنصة. لا يزال دعم عرض الصفحات والإطارات والرسوم المتحركة متاحًا.
مساعدو الموارد — ReferenceCss / ReferenceScripts
أصدر وسوم <link>/<script> للموارد المدمجة التي يقدمها UseDoconutResources()، بترتيب الاعتماد الصحيح. تُصدر الحزم للميزات المقيدة بالترخيص مثل البحث والتعليق فقط عندما يتيح الترخيص ذلك، مما يحافظ على توافق واجهة المستخدم للعميل مع سلوك الخادم.
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 ضمن سياسة أمان المحتوى التي تحظر السكريبتات المضمّنة).
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))هل كانت هذه الصفحة مفيدة؟