عارض
الفئة الرئيسية لعرض المستندات
Viewer (namespace Doconut) هو نقطة الدخول العامة لفتح المستندات من صفحات Razor، وحدات تحكم MVC، مكونات Blazor، أو واجهات برمجة تطبيقات بسيطة. إنه مغلق، مسجل كخدمة عابرة بواسطة AddDoconut()، ويتم حله عبر حقن الباني — لا تقم بإنشائه مباشرةً.
المكتبة السابقة لـ .NET Standard كانت تعرض بانيًا عامًا يأخذ ذاكرة التخزين المؤقت، وموصل سياق HTTP، ومسار أو أكثر للتراخيص. هذا الباني لم يعد موجودًا؛ فإن مخطط الخدمة يزود بهذه الاعتمادات.
Viewer لا يحمل أي حالة per-request ويقصد عدم تنفيذ IDisposable: جلسات المستند تعيش بشكل مستقل في ذاكرة التخزين المؤقت للجلسة، لذا لا يمكن لتخلص الخدمة أن يغلق مستندًا مفتوحًا (انظر المفاهيم الأساسية → كيف يعمل العارض).
OpenDocumentAsync
يفتح مستندًا ويعيد رمز الجلسة الذي يستخدمه عنصر واجهة العميل لجميع الطلبات اللاحقة. كل عملية فتح تكون غير متزامنة — لا يوجد OpenDocument متزامن.
| التحميل الزائد | متى يستخدم |
|---|---|
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 الامتداد الصحيح — فهو يحدد اكتشاف الصيغة |
// فتح بسيط
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 لتصوير شريط Ribbon مرخص فقط عندما يكون الخادم سيقدمه فعليًا — راجع البدء السريع.
خيارات المستند
خيارات مستقلة عن الصيغة لكل فتح (المساحة الاسم 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 بدلاً من ذلك. لاحظ حالة الأحرف — المكتبة السابقة كانت تكتب هذا IsWebfarm. |
string | WebFarmPath | "" | قديمة — لا تأثير لها. استخدم FileShareConfig.RootPath، كما هو موضح في النشر الموزع. كانت تُكتب سابقًا WebfarmPath. |
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 لكل صفحة مع دمج التعليقات التوضيحية |
كل واحدة من هذه تتطلب رمز الجلسة. شكل GetAnnotationManager(pageWidth, pageHeight) الخالي من الجلسة في المكتبة السابقة لا يزال موجودًا لإنشاء التعليقات التوضيحية خارج الجلسة، لكن تحميلها لا يزال يتطلب رمزًا.
بيانات تعريف DICOM
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)الطريقة موجودة لتوافق واجهة برمجة التطبيقات، لكن هذه الحزمة لا يمكنها توفير علامات DICOM التقنية: قارئ البيانات الوصفية يُوزَّع فقط بإصدار .NET 8. تُعيد null لجلسات DICOM وغير DICOM؛ في جلسة DICOM تُكتب أيضًا تحذير لمرة واحدة يشرح قيود المنصة. لا يزال دعم عرض الصفحات والإطارات والرسوم المتحركة متاحًا.
مساعدي الموارد — ReferenceCss / ReferenceScripts
أصدر وسوم <link>/<script> للموارد المدمجة التي يقدمها UseDoconutResources()، بترتيب الاعتماد الصحيح. تُصدر الحزم للميزات المقيدة بالترخيص مثل البحث والتعليقات التوضيحية فقط عندما يسمح الترخيص بها، مما يحافظ على توافق واجهة المستخدم للعميل مع سلوك الخادم.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + viewer + search + annotation
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 }))هذه المساعدات هي الطريقة المدعومة لتوفير موارد المتصفح. يجب على التطبيقات التي نسخت docViewer.js و documentLinks.js و docViewer.UI.js إلى wwwroot إزالة تلك النسخ بمجرد أن تُظهر الصفحة من الوسوم الصادرة.
هل كانت هذه الصفحة مفيدة؟