عارض
الفئة الرئيسية لعرض المستندات
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 للجلسات المفتوحة عبر ملحق DICOM؛ null للمستندات غير 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 }))هل كانت هذه الصفحة مفيدة؟