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` في جذر الموقع؛ وإلا يكون الفرع حيث يطابق المضيف `UseDoconut()`، بدون علامة `/` في البداية (`"doconut"` يعني `/doconut/DocImage.axd`).
`string`	`ResPath`	`"doconut-res/images"` (26.9.0; `"doconut-res"` before)	المجلد الذي يحمل منه الودجت صوره الخاصة: مجلد `images` داخل `ResourcesPath`، بدون علامة `/` في البداية.
`string`	`FitType`	`"width"`	`"width"`، `"height"` أو فارغ لعدم التكيّف التلقائي. `"page"` غير مقبول في الودجت الحالي.
`bool`	`RetryOn409`	`false`	تمكين الاستطلاع عندما تستجيب عملية إنتاج الصفحات غير المتزامنة/الموزعة بـ `202 Accepted`؛ كما يتم قبول `409` للتوافق مع الخوادم القديمة. غير مطلوب للعارض المتزامن العادي.

csharp

var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "doconut",           // no leading '/': the viewer adds it ("/doconut" would become //doconut, another host)
    ResPath = "doconut-res/images",
    ShowHyperlinks = true
};

تحويل 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`	قيمة `maxZoom` في جافاسكريبت تختلف عن C# (`300`).
`showToolTip` / `toolTipPageText`	`true` / `"Page "`	تلميح موقع الصفحة.
`format` / `doc` / `AccessToken`	`""` / `0` / `""`	قيم التهيئة الداخلية؛ عادةً ما يتم ملؤها بواسطة `View(token)`.
`debugMode`	`false`	تشخيصات إضافية للعميل.
`FitType`	`""`	لا يوجد تعديل تلقائي ما لم يتم توفيره.
`BasePath`	`"DocImage.axd"`	الإعداد الافتراضي التاريخي للعميل محفوظ للتوافق. يجب على مضيفي ASP.NET Core الحاليين تعيينه صراحةً إلى فرع middleware المربوط.
`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: 'doconut',
    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 يحتفظ باسمه التاريخي. يُستخدم لإنتاج الصفحات غير المتزامنة ويعيد محاولة استجابة الجاهزية الحالية 202 Accepted بالإضافة إلى إشارة 409 Conflict الأقدم. عند التمكين، تقوم الأداة بالاستطلاع باستخدام هذه الإعدادات الافتراضية لجافاسكريبت:

الخيار	الافتراضي
`retryInitialDelayMs`	`250`
`retryBackoffFactor`	`1.6`
`retryMaxDelayMs`	`2500`
`retryMaxAttempts`	`60`
`retryMaxTotalMs`	`120000`

اتركه معطلاً للمستعرض العادي. تمكينه لا يمكن أن يجعل عرضًا متزامنًا غير مدعومًا غير متزامن.

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

DoconutOptions.MiddlewarePath يجب أن يصف الفرع الذي تقوم بربطه فعليًا.
BasePath يجب أن يستهدف ذلك الفرع، مكتوبًا بدون علامة / في البداية ('doconut'، وليس '/doconut': العارض يضيف الشرطة، و//doconut/... هو طلب إلى مضيف آخر).
DoconutOptions.ResourcesPath هو مسار المورد المدمج.
ResPath عادةً ما يستهدف المجلد الفرعي images الخاص به، أيضًا بدون علامة / في البداية ('doconut-res/images').
ExtractHyperlinks يجب أن يكون مفعَّلاً في إعداد تنسيق الخادم قبل أن يتمكن showHyperlinks من عرض أي شيء.