ViewerConfig – Doconut الوثائق

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

خصائص 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`	`"/"`	الفرع الذي يطابق `UseDoconut()` على المضيف.
`string`	`ResPath`	`"doconut-res"`	قاعدة الموارد المستخدمة من قبل عنصر الواجهة. في إعداد عادي يجب توجيهها إلى `<ResourcesPath>/images`.
`string`	`FitType`	`"width"`	`"width"` أو `"height"` أو فارغ لعدم الملاءمة التلقائية. `"page"` غير مقبول في العنصر الحالي.
`bool`	`RetryOn409`	`false`	تمكين الاستطلاع عندما يرد طلب صفحة غير متزامن/موزع بـ `409`. غير مطلوب في المشاهد المتزامن العادي.

csharp

var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "/doconut",
    ResPath = "/doconut-res/images",
    ShowHyperlinks = true
};

تعيين C# إلى جافاسكريبت

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

C#	جافاسكريبت
`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.
`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>

ردود النداء (Callbacks)

رد النداء	الوسائط	الغرض
`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)`

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

إعادة المحاولة بعد HTTP 409

retryOn409 مخصص لإنتاج الصفحات غير المتزامن. عند تفعيله، يستطلع العنصر باستخدام القيم الافتراضية لجافاسكريبت التالية:

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

اتركه معطَّلًا للمشاهد العادي. تمكينه لا يمكن أن يجعل عرضًا متزامنًا غير مدعوم يتحول إلى غير متزامن.

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

يجب أن يصف DoconutOptions.MiddlewarePath الفرع الذي تقوم فعليًا بربطه.
يجب أن يستهدف BasePath ذلك الفرع.
DoconutOptions.ResourcesPath هو مسار المورد المدمج.
عادةً ما يستهدف ResPath المجلد الفرعي /images الخاص به.
يجب تمكين ExtractHyperlinks في تكوين تنسيق الخادم قبل أن يتمكن showHyperlinks من عرض أي شيء.