ViewerConfig – Doconut الوثائق

ViewerConfig (namespace Doconut) يصف مظهر وسلوك عارض المتصفح. لا يؤثر على جودة عرض المستند؛ استخدم تكوين تنسيق لذلك. فئة C# وإضافة JavaScript القديمة لها إعدادات افتراضية مختلفة، لذا قم بربط القيم صراحةً.

خصائص C#

النوع	الخاصية	الافتراضي	الوصف
`bool`	`ShowThumbs`	`true`	إظهار لوحة المصغرات.
`bool`	`AutoLoad`	`false`	تحميل تلقائي بعد التهيئة. تدفق الرموز العادي يستدعي `View(token)` صراحةً.
`bool`	`AutoFocus`	`true`	نقل تركيز المتصفح/التمرير إلى العارض أثناء التهيئة.
`bool`	`AutoPageFocus`	`true`	إبقاء المصغرة الحالية مرئية أثناء تغيير الصفحات.
`int`	`PageZoom`	`100`	نسبة التكبير الأولية.
`int`	`ZoomStep`	`10`	النسبة المضافة أو المزالة بأوامر التكبير.
`int`	`MaxZoom`	`300`	الحد الأقصى لنسبة التكبير.
`bool`	`ShowToolTip`	`true`	إظهار تلميح موضع الصفحة أثناء التمرير.
`string`	`ToolTipPageText`	`"Page "`	البادئة المستخدمة في تلميح الصفحة.
`bool`	`CacheEnabled`	`false`	الاحتفاظ بنافذة متحركة من صور الصفحات في ذاكرة المتصفح. لا يستخدم `localStorage`.
`bool`	`LargeDoc`	`false`	إضافة عناصر الصفحات على دفعات زمنية للوثائق الكبيرة.
`bool`	`ShowHyperlinks`	`false`	عرض طبقات الروابط الفوقية عندما يستخرجها تكوين الخادم.
`bool`	`FixedZoom`	`true`	استخدام نسبة تكبير ثابتة بدلاً من إعادة حساب استجابية.
`int`	`FixedZoomPercent`	`100`	تكبير ثابت لسطح المكتب.
`int`	`FixedZoomPercentMobile`	`75`	تكبير ثابت للجوال.
`string`	`BasePath`	`"/"`	المكان الذي يرسل فيه العارض طلبات الصفحات. `"/"` هو معالج `DocImage.axd` في جذر الموقع. لتطبيق في دليل افتراضي، استخدم اسم الدليل بدون بادئة `/` (`"myapp"` يعني `/myapp/DocImage.axd`).
`string`	`ResPath`	`"doconut-res/images"`	المجلد الذي يحمل منه الودجت صوره الخاصة: مجلد `images` تحت `ResourcesPath`، بدون بادئة `/`.
`string`	`FitType`	`"width"`	`"width"`، `"height"`، أو فارغ لعدم وجود ملاءمة تلقائية. `"page"` غير مقبول من قبل الودجت الحالي.
`bool`	`RetryOn409`	`false`	يعيد محاولة طلبات الصفحات التي تجيب بـ "ما زال يتم العرض". `DocImage.axd` يعرض بشكل متزامن ولا يرسل تلك الإشارة أبداً؛ اتركه `false`.

csharp

var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "/",                 // \"/\" = معالج DocImage.axd في جذر الموقع (Web.config)
    ResPath = "doconut-res/images", // مجلد الصور تحت ResourcesPath، بدون '/' في البداية
    ShowHyperlinks = true
};
// أصدره باستخدام viewer.RenderViewer(\"viewerEl\", token, config) - راجع مرجع Viewer.

إنشاء ViewerConfig باستخدام RenderViewer

Viewer.RenderViewer(elementId, token, config) يحول ViewerConfig إلى برنامج تهيئة الودجت. يكتب ستة من الخصائص أعلاه — BasePath، ResPath، ShowThumbs، AutoLoad، PageZoom، وFitType — ثم يستدعي View(token). الخصائص الأخرى لا تُكتب: بالنسبة لـ MaxZoom، ShowHyperlinks، إعدادات التكبير، أو أي رد نداء، قم بتهيئة الودجت بنفسك باستخدام خيارات JavaScript أدناه. راجع Viewer للحصول على RenderViewer.

ربط C# إلى JavaScript

لا تمرر ViewerConfig المُسلسل مباشرةً إلى docViewer(...). معظم مفاتيح الودجت هي camelCase، بينما ثلاثة مفاتيح مسار/ملاءمة معتمدة هي PascalCase.

C#	JavaScript
`ShowThumbs`	`showThumbs`
`AutoLoad`	`autoLoad`
`AutoFocus`	`autoFocus`
`AutoPageFocus`	`autoPageFocus`
`PageZoom`	`pageZoom`
`ZoomStep`	`zoomStep`
`MaxZoom`	`maxZoom`
`ShowToolTip`	`showToolTip`
`ToolTipPageText`	`toolTipPageText`
`CacheEnabled`	`cacheEnabled`
`LargeDoc`	`largeDoc`
`ShowHyperlinks`	`showHyperlinks`
`FixedZoom`	`fixedZoom`
`FixedZoomPercent`	`fixedZoomPercent`
`FixedZoomPercentMobile`	`fixedZoomPercentMobile`
`BasePath`	`BasePath`
`ResPath`	`ResPath`
`FitType`	`FitType`
`RetryOn409`	`retryOn409`

الإعدادات الافتراضية لجافا سكريبت

الودجت يحتوي على إعدادات افتراضية أقدم تختلف عن فئة C#. القيم التالية تأتي من تنفيذ docViewer.js الحالي.

الخيار	الافتراضي	ملاحظات
`leftMinWidth` / `leftMaxWidth`	`220` / `800`	حدود عرض لوحة الصورة المصغرة.
`showThumbs`	`true`	رؤية الصورة المصغرة الأولية.
`autoFocus` / `autoPageFocus`	`true` / `false`	`autoPageFocus` يختلف عن الإعداد الافتراضي في C#.
`thumbWidth` / `thumbHeight` / `thumbPadding`	`150` / `200` / `10`	هندسة الصورة المصغرة بالبكسل.
`pageZoom` / `zoomStep` / `maxZoom`	`100` / `10` / `200`	JavaScript `maxZoom` يختلف عن C# (`300`).
`showToolTip` / `toolTipPageText`	`true` / `"Page "`	تلميح موقع الصفحة.
`format` / `doc` / `AccessToken`	`""` / `0` / `""`	قيم تهيئة داخلية؛ عادةً ما يتم ملؤها بواسطة `View(token)`.
`debugMode`	`false`	تشخيصات إضافية للعميل.
`FitType`	`""`	لا يوجد تعديل تلقائي ما لم يتم توفيره.
`BasePath`	`"DocImage.axd"`	الإعداد الافتراضي القديم. عيّنه صراحةً: `'/'` للمعالج في جذر الموقع.
`ResPath`	`""`	عيّن صراحةً مسار الصور المدمجة.
`cacheEnabled` / `cacheCount` / `cacheDelay`	`false` / `3` / `3`	نافذة تحميل الصفحات مسبقًا في الذاكرة والتأخير.
`autoLoad`	`false`	يُنصح بتدفق الرموز الصريح.
`largeDoc`	`true`	يختلف عن الإعداد الافتراضي في C#.
`fixedZoom`	`false`	يختلف عن الإعداد الافتراضي في C#.
`fixedZoomPercent` / `fixedZoomPercentMobile`	`100` / `50`	القيمة للهواتف المحمولة تختلف عن C# (`75`).
`showHyperlinks`	`true`	يتطلب استخراجًا من جانب الخادم لإنتاج الطبقات الفوقية.

قم بتعيين جميع القيم المهمة سلوكيًا بدلاً من الاعتماد على أي من مجموعتي الإعدادات الافتراضية:

html

<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

<script>
const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad: false,
    autoFocus: true,
    autoPageFocus: true,
    pageZoom: 100,
    zoomStep: 10,
    maxZoom: 300,
    FitType: 'width',
    cacheEnabled: false,
    largeDoc: false,
    showHyperlinks: true,
    fixedZoom: true,
    fixedZoomPercent: 100,
    fixedZoomPercentMobile: 75,
    BasePath: '/',
    ResPath: 'doconut-res/images',
    onViewerReady: function () {},
    onError: function (message) { console.error('DocViewer:', message); }
});
</script>

الدوال الراجعة

الدالة الراجعة	الوسائط	الغرض
`onPageLoading`	`pageNum`	يبدأ طلب صفحة.
`onPageLoaded`	`pageNum`	انتهى تحميل صورة الصفحة.
`onThumbnailClicked`	`pageNum`	اختار المستخدم صورة مصغرة.
`onPageClicked`	`pageNum`	اختار المستخدم صفحة.
`onDoubleClick`	لا شيء	تلقى العارض نقرة مزدوجة.
`onViewerBusy`	لا شيء	دخل العارض حالة الانشغال.
`onViewerReady`	لا شيء	اكتملت عملية التهيئة.
`onViewerError`	لا شيء	دخل العارض حالة الخطأ.
`onError`	`message`	عادت عملية برسالة خطأ.
`onCopy`	`data`	تتوفر بيانات نسخ النص.
`onAutoLoadStatus`	`pageNum`	تقدم التحميل التلقائي إلى صفحة.
`onThumbsShown`	لا شيء	أصبحت لوحة الصور المصغرة مرئية.
`onAnnLoaded`	لا شيء	تم تحميل بيانات التعليقات التوضيحية.
`onAnnSaved`	لا شيء	تم حفظ بيانات التعليقات التوضيحية.
`onAnnSaveError`	لا شيء	فشل حفظ التعليقات التوضيحية.
`onAnnClosed`	لا شيء	أُغلق واجهة التعليقات التوضيحية.

احرص على أن تكون الدوال الراجعة سريعة؛ أرسل بيانات القياس عن بُعد بشكل غير متزامن ولا تحجب عملية عرض الصفحة.

مجموعات الطرق العامة

المجموعة	الطرق الشائعة
دورة الحياة	`View(token, accessToken?)`, `Close(server?)`, `Token()`, `Init()`, `IsLoaded()`
التنقل	`GotoPage(page)`, `ShowPage(page, focus?)`, `Next(next)`, `CurrentPage()`, `TotalPages()`
التكبير والملاءمة	`Zoom(zoomIn)`, `CurrentZoom()`, `FitType(value)`, `Refit()`
الاتجاه	`Rotate(page, angle)`, `Flip(page, flipType)`
الصور المصغرة	`HideThumbs(hide)`, `ThumbSize(size)`, `ReloadThumbs(width)`, `ScrollToThumb(thumb)`
البحث	`CanSearch()`, `Search(...)`, `SearchMatchCount()`, `SearchSummary(...)`, `GotoSearchMatch(...)`
التعليقات التوضيحية	`SaveAnnotations()`, `GetAnnotations()`, `PushAnnotations(...)`, `CloseAnnotations(...)`, `ShowAnnotations(...)`
النسخ	`Copy(...)`, `CopyPage(pageNumber)`, `CopyMode(enabled)`

يحتوي ملف جافا سكريبت أيضًا على مساعدات داخلية. اعتبر فقط الطرق المستخدمة من قبل واجهة المستخدم المرجعية والموثقة هنا أو في أدلة الميزات كنقاط دمج ثابتة.

خيارات إعادة المحاولة

تقبل الواجهة أيضًا retryOn409 وإعدادات التراجع الخاصة به (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs). إنها تخدم عمليات النشر التي تُنتج صفحاتها في الخلفية. DocImage.axd يُظهر كل صفحة أثناء الطلب، لذا اترك retryOn409 مُعطَّل.

قائمة التحقق من المسار

BasePath هو '/' عندما يكون معالج DocImage.axd في جذر الموقع — سمة path للمعالج في Web.config تحدد أين يرد. في دليل افتراضي، استخدم اسم الدليل بدون / أولية ('myapp'، وليس '/myapp': العارض يضيف الشرط المائل، و//myapp/... هو طلب إلى مضيف آخر).
DoconutOptions.ResourcesPath هو المكان الذي يخدم فيه وحدة الموارد الملفات المدمجة (/doconut-res بشكل افتراضي).
ResPath يستهدف المجلد الفرعي images الخاص به، أيضًا بدون / أولية ('doconut-res/images'). توجيهه إلى 'doconut-res' يجعل كل أيقونة تُعيد 404 بينما لا يزال المستند يُعرض.
في MVC، يجب أن يتبع routes.IgnoreRoute("doconut-res/{*pathInfo}") بعد ResourcesPath إذا قمت بتغييره.
يجب تمكين ExtractHyperlinks في تكوين تنسيق الخادم قبل أن يتمكن showHyperlinks من عرض أي شيء.