عارض
الفئة الرئيسية لعرض المستندات
Viewer (المساحة الاسمية Doconut) هي نقطة الدخول العامة لفتح المستندات من وحدات تحكم MVC، صفحات Web Forms، والمعالجات. إنها خدمة عابر مكوّنة بواسطة DoconutHost.Initialize؛ حلّها حيث تستخدمها:
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 الامتداد الصحيح — فهو يختار الصيغة |
// فتح بسيط
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 وغيرها من الشفرات التي لا تستخدم الصفحات غير المتزامنة:
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 في ملحق المحول.
إغلاق المستند
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):
| النوع | الخاصية | الافتراضي | الوصف |
|---|---|---|---|
string | Password | "" | كلمة المرور للمستندات المحمية (تُنسخ تلقائياً إلى تكوين التنسيق). |
string | Watermark | "" | نص علامة مائية مخصصة يُرسم على الصفحات المعروضة — انظر أدناه. |
int | TimeOut | 60 | انتهاء صلاحية الجلسة المتحركة، بالدقائق. |
string | BrowserId | "" | مزارع الويب: المتصفح المرتبط بالتذكرة الموقعة. اضبطه باستخدام DoconutFarmBinding.EnsureBrowserId (انظر الجلسات والأمان). |
string | UserId | "" | مزارع الويب: المستخدم الموقع الذي ترتبط به التذكرة، من DoconutFarmBinding.ResolveUserId. |
int | ImageResolution | 0 | مهمل. اضبط ImageResolution في تكوين التنسيق بدلاً من ذلك. |
bool | IsSecured | true | محجوز؛ غير مفروض. التحكم في الوصول هو DoconutOptions.UnsafeMode. |
bool | IsWebFarm / string WebFarmPath | false / "" | محفوظ للشفرة التي تم ترحيلها من الحزمة الكلاسيكية. لا تقوم بتفعيل وضع المزرعة — AddDoconutDistributed يفعل ذلك. |
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 | عائلة الخط. يجب أن تكون مثبتة على الخادم — خادم 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
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) تُصدر فقط عندما يمنح الترخيص إياها.
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
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).
هل كانت هذه الصفحة مفيدة؟