ViewerConfig

Client viewer widget options

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

تغييران على جانب العميل في هذا الإصدار يفشلان بصمت. يتم تمرير وظائف المعالج كخيارات — لم يعد العنصر يستمد استدعاءات الأحداث من معرف الحاوية — ويجب أن يشير ResPath إلى بادئة الموارد بدلاً من جذر التطبيق. كلاهما يترك الخادم يعمل بشكل كامل ولا يُظهر أي شيء في وحدة تحكم المتصفح. إذا كنت تنقل صفحة من المكتبة السابقة، اقرأ النداءات وقائمة فحص المسار قبل أي شيء آخر.

خصائص C#

النوعالخاصيةالافتراضيالوصف
boolShowThumbstrueإظهار لوحة الصور المصغرة.
boolAutoLoadfalseتحميل تلقائي بعد التهيئة. تدفق الرموز العادي يستدعي View(token) صراحةً.
boolAutoFocustrueنقل تركيز/تمرير المتصفح إلى العارض أثناء التهيئة.
boolAutoPageFocustrueإبقاء الصورة المصغرة الحالية مرئية أثناء تغيير الصفحات.
intPageZoom100نسبة التكبير الأولية.
intZoomStep10النسبة المضافة أو المزالة بأوامر التكبير.
intMaxZoom300الحد الأقصى لنسبة التكبير.
boolShowToolTiptrueإظهار تلميح موضع الصفحة أثناء التمرير.
stringToolTipPageText"Page "البادئة المستخدمة في تلميح الصفحة.
boolCacheEnabledfalseالاحتفاظ بنافذة متحركة من صور الصفحات في ذاكرة المتصفح. لا يستخدم localStorage.
boolLargeDocfalseإضافة عناصر الصفحات على دفعات زمنية للوثائق الكبيرة.
boolShowHyperlinksfalseعرض طبقات الروابط الفوقية عندما يستخرجها تكوين الخادم.
boolFixedZoomtrueاستخدام نسبة تكبير ثابتة بدلاً من إعادة حساب استجابية.
intFixedZoomPercent100تكبير ثابت لسطح المكتب.
intFixedZoomPercentMobile75تكبير ثابت للجوال.
stringBasePath"/"المكان الذي يرسل فيه العارض طلبات الصفحات. "/" هو DocImage.axd في جذر الموقع؛ وإلا الفرع حيث يطابق المضيف UseDoconut()، بدون بادئة / ("doconut" يعني /doconut/DocImage.axd).
stringResPath"doconut-res/images" (26.9.0; "doconut-res" before)مجلد يحمل منه العنصر صوره الخاصة: مجلد images تحت ResourcesPath، بدون بادئة /.
stringFitType"width""width"، "height"، أو فارغ لعدم وجود ملاءمة تلقائية. "page" غير مقبول من قبل العنصر الحالي.
boolRetryOn409falseتمكين الاستطلاع عندما تستجيب إنتاج الصفحات غير المتزامنة/الموزعة 202 Accepted؛ 409 مقبول أيضاً للتوافق مع الخوادم القديمة. غير مطلوب من قبل العارض المتزامن العادي.
csharp
var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "doconut",           // لا توجد '/' في البداية: المشاهد يضيفها ("/doconut" سيتحول إلى //doconut, مضيف آخر)
    ResPath = "doconut-res/images",
    ShowHyperlinks = true
};

تحويل C# إلى JavaScript

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

C#JavaScript
ShowThumbsshowThumbs
AutoLoadautoLoad
AutoFocusautoFocus
AutoPageFocusautoPageFocus
PageZoompageZoom
ZoomStepzoomStep
MaxZoommaxZoom
ShowToolTipshowToolTip
ToolTipPageTexttoolTipPageText
CacheEnabledcacheEnabled
LargeDoclargeDoc
ShowHyperlinksshowHyperlinks
FixedZoomfixedZoom
FixedZoomPercentfixedZoomPercent
FixedZoomPercentMobilefixedZoomPercentMobile
BasePathBasePath
ResPathResPath
FitTypeFitType
RetryOn409retryOn409

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

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

الخيارالافتراضيملاحظات
leftMinWidth / leftMaxWidth220 / 800حدود عرض لوحة الصور المصغرة.
showThumbstrueرؤية الصورة المصغرة الأولية.
autoFocus / autoPageFocustrue / falseautoPageFocus يختلف عن الإعداد الافتراضي لـ C#.
thumbWidth / thumbHeight / thumbPadding150 / 200 / 10هندسة الصورة المصغرة بالبكسل.
pageZoom / zoomStep / maxZoom100 / 10 / 200JavaScript maxZoom يختلف عن C# (300).
showToolTip / toolTipPageTexttrue / "Page "تلميح موضع الصفحة.
format / doc / AccessToken"" / 0 / ""قيم التهيئة الداخلية؛ عادةً ما يتم تعبئتها بواسطة View(token).
debugModefalseتشخيصات إضافية للعميل.
FitType""لا يوجد ضبط تلقائي ما لم يتم توفيره.
BasePath"DocImage.axd"الإعداد الافتراضي التاريخي للعميل محفوظ للتوافق. يجب على مضيفي ASP.NET Core الحاليين تعيينه صراحةً إلى فرع middleware المقابل.
ResPath""تعيين صراحةً إلى مسار الصور المضمنة.
cacheEnabled / cacheCount / cacheDelayfalse / 3 / 3نافذة تحميل الصفحات مسبقًا في الذاكرة والتأخير.
autoLoadfalseيُنصَح بتدفق الرموز الصريح.
largeDoctrueيختلف عن الإعداد الافتراضي لـ C#.
fixedZoomfalseيختلف عن الإعداد الافتراضي لـ C#.
fixedZoomPercent / fixedZoomPercentMobile100 / 50القيمة المحمولة تختلف عن C# (75).
showHyperlinkstrueيتطلب استخراجًا من جانب الخادم لإنتاج الطبقات فوقية.

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

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>

ردود النداء

رد النداءالمعاملاتالغرض
onPageLoadingpageNumطلب صفحة يبدأ.
onPageLoadedpageNumانتهى تحميل صورة الصفحة.
onThumbnailClickedpageNumالمستخدم اختار صورة مصغرة.
onPageClickedpageNumالمستخدم اختار صفحة.
onDoubleClicknoneالمشاهد تلقى نقرة مزدوجة.
onViewerBusynoneالمشاهد دخل حالة مشغولة.
onViewerReadynoneاكتملت التهيئة.
onViewerErrornoneالمشاهد دخل حالة الخطأ.
onErrormessageعملية أرجعت رسالة خطأ.
onCopydataبيانات نسخ النص متاحة.
onAutoLoadStatuspageNumالتلقائي التحميل تقدم إلى صفحة.
onThumbsShownnoneلوحة الصور المصغرة أصبحت مرئية.
onAnnLoadednoneتم تحميل بيانات التعليق.
onAnnSavednoneتم حفظ بيانات التعليق.
onAnnSaveErrornoneفشل حفظ التعليق.
onAnnClosednoneواجهة التعليق أغلقت.

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

كل واحد من هذه هو خيار في كائن التهيئة. المشاهد السابق كان يبحث عن الدوال العالمية التي اشتق أسماؤها من معرف الحاوية — صفحة تحتوي على <div id="div_ctlDoc"> كان عليها فقط إعلان function ctlDoc_OnViewerReady(). تم إزالة ذلك البحث. مرّر الدالة صراحةً:

javascript
function ctlDoc_OnViewerBusy() { /* اعرض مؤشر الانشغال الخاص بك */ }
function ctlDoc_OnViewerReady() { /* أخفِه */ }
function ctlDoc_Copy(text) { /* استخدم النص المنسوخ */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* أبلغ عن التقدم */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... خياراتك الحالية ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // تم العثور عليه بالاسم
    onViewerReady:    ctlDoc_OnViewerReady,     // تم العثور عليه بالاسم
    onCopy:           ctlDoc_Copy,              // كان ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // كان ctlDoc_AutoLoadStatus(page)
});

البحث القديم كان محاطًا بـ catch فارغ، لذا لم يتم الإبلاغ عن شيء. في هذا الإصدار الدوال ببساطة لا تُنفّذ أبداً: العرض الشائع هو مؤشر تحميل مشغول لا يتوقف أبداً، لأن المعالج الذي كان يخفيه كان onViewerReady. المستند خلفه يُعرض بشكل صحيح.

ما زال يتم البحث عن ربطتين لحفظ التعليق بالاسم: SaveAnnotations() يستدعي <elementId>_BeforeAnnSave() و<elementId>_DeletedAnnotationIds() عندما تكون موجودة، باستخدام المعرف الكامل للعنصر (div_ctlDoc_BeforeAnnSave للمثال أعلاه).

لا توجد رد نداء للنقر على الرابط — معالجة الروابط مدمجة وتُقَدَّم بواسطة showHyperlinks.

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

المجموعةالطرق المشتركة
دورة الحياة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)

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

إعادة المحاولة أثناء استمرار عرض صفحة موزعة

retryOn409 يحتفظ باسمه التاريخي. هو مخصص لإنتاج الصفحات غير المتزامن ويعيد محاولة استجابة جاهزية 202 Accepted الحالية وكذلك إشارة 409 Conflict الأقدم. عند التفعيل، يقوم الودجت بالاستطلاع باستخدام هذه القيم الافتراضية لجافاسكريبت:

الخيارالافتراضي
retryInitialDelayMs250
retryBackoffFactor1.6
retryMaxDelayMs2500
retryMaxAttempts150
retryMaxTotalMs300000

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

فعّله عندما تُقدم الصفحات من تخزين مشترك باستخدام FirstPagePriority، حيث تُجيب الصفحات اللاحقة بصورة شرعية على 202 Accepted حتى تُكتب. العميل الذي لا يعيد المحاولة يُظهر بلاطات مكسورة للصفحات التي لا تزال تُعرض — انظر التوزيعات الموزعة.

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

  • DoconutOptions.MiddlewarePath يجب أن يصف الفرع الذي تقوم بربطه فعليًا.
  • BasePath يجب أن يستهدف ذلك الفرع، مكتوبًا دون / البادئ ('doconut'، وليس '/doconut': يضيف العارض الشرطة المائلة، و//doconut/... هو طلب إلى مضيف آخر). إعداد شائع يحافظ على شكل طلب DocImage.axd التاريخي على فرع MapWhen وبالتالي يضبط BasePath: '/'.
  • DoconutOptions.ResourcesPath هو مسار المورد المضمن.
  • ResPath عادةً ما يستهدف المجلد الفرعي images الخاص به، دون / البادئ — 'doconut-res/images' مع البادئة الافتراضية. كان ResPath الفارغ صحيحًا في المكتبة السابقة، حيث كانت الموارد تأتي من جذر التطبيق؛ إنه غير صحيح هنا، ويتسبب في فشل دون خطأ.
  • ExtractHyperlinks يجب أن يكون مفعلاً في تكوين تنسيق الخادم قبل أن يتمكن showHyperlinks من عرض أي شيء.

هل كانت هذه الصفحة مفيدة؟