ViewerConfig
Client viewer widget options
ViewerConfig (namespace Doconut) يصف مظهر وسلوك عارض المتصفح. لا يؤثر على جودة عرض المستند؛ استخدم تكوين تنسيق لذلك. فئة C# وعنصر واجهة JavaScript القديم لديهما إعدادات افتراضية مختلفة، لذا يجب تعيين القيم صراحةً.
تغييران على جانب العميل في هذا الإصدار يفشلان بصمت. يتم تمرير وظائف المعالج كخيارات — لم يعد العنصر يستمد استدعاءات الأحداث من معرف الحاوية — ويجب أن يشير
ResPathإلى بادئة الموارد بدلاً من جذر التطبيق. كلاهما يترك الخادم يعمل بشكل كامل ولا يُظهر أي شيء في وحدة تحكم المتصفح. إذا كنت تنقل صفحة من المكتبة السابقة، اقرأ النداءات وقائمة فحص المسار قبل أي شيء آخر.
خصائص 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 مقبول أيضاً للتوافق مع الخوادم القديمة. غير مطلوب من قبل العارض المتزامن العادي. |
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 |
|---|---|
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" | الإعداد الافتراضي التاريخي للعميل محفوظ للتوافق. يجب على مضيفي 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 | يتطلب استخراجًا من جانب الخادم لإنتاج الطبقات فوقية. |
قم بتعيين جميع القيم ذات الأهمية السلوكية بدلاً من الاعتماد على أي من مجموعتي الإعدادات الافتراضية:
<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 | none | المشاهد تلقى نقرة مزدوجة. |
onViewerBusy | none | المشاهد دخل حالة مشغولة. |
onViewerReady | none | اكتملت التهيئة. |
onViewerError | none | المشاهد دخل حالة الخطأ. |
onError | message | عملية أرجعت رسالة خطأ. |
onCopy | data | بيانات نسخ النص متاحة. |
onAutoLoadStatus | pageNum | التلقائي التحميل تقدم إلى صفحة. |
onThumbsShown | none | لوحة الصور المصغرة أصبحت مرئية. |
onAnnLoaded | none | تم تحميل بيانات التعليق. |
onAnnSaved | none | تم حفظ بيانات التعليق. |
onAnnSaveError | none | فشل حفظ التعليق. |
onAnnClosed | none | واجهة التعليق أغلقت. |
حافظ على ردود النداء سريعة؛ أرسل بيانات القياس بشكل غير متزامن ولا تحجب عرض الصفحة.
كل واحد من هذه هو خيار في كائن التهيئة. المشاهد السابق كان يبحث عن الدوال العالمية التي اشتق أسماؤها من معرف الحاوية — صفحة تحتوي على <div id="div_ctlDoc"> كان عليها فقط إعلان function ctlDoc_OnViewerReady(). تم إزالة ذلك البحث. مرّر الدالة صراحةً:
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 الأقدم. عند التفعيل، يقوم الودجت بالاستطلاع باستخدام هذه القيم الافتراضية لجافاسكريبت:
| الخيار | الافتراضي |
|---|---|
retryInitialDelayMs | 250 |
retryBackoffFactor | 1.6 |
retryMaxDelayMs | 2500 |
retryMaxAttempts | 150 |
retryMaxTotalMs | 300000 |
اتركه معطلاً للعارض العادي ذو العقدة الواحدة. تمكينه لا يمكن أن يجعل عرضًا متزامنًا غير مدعومًا غير متزامن.
فعّله عندما تُقدم الصفحات من تخزين مشترك باستخدام FirstPagePriority، حيث تُجيب الصفحات اللاحقة بصورة شرعية على 202 Accepted حتى تُكتب. العميل الذي لا يعيد المحاولة يُظهر بلاطات مكسورة للصفحات التي لا تزال تُعرض — انظر التوزيعات الموزعة.
قائمة التحقق من المسار
DoconutOptions.MiddlewarePathيجب أن يصف الفرع الذي تقوم بربطه فعليًا.BasePathيجب أن يستهدف ذلك الفرع، مكتوبًا دون/البادئ ('doconut'، وليس'/doconut': يضيف العارض الشرطة المائلة، و//doconut/...هو طلب إلى مضيف آخر). إعداد شائع يحافظ على شكل طلبDocImage.axdالتاريخي على فرعMapWhenوبالتالي يضبطBasePath: '/'.DoconutOptions.ResourcesPathهو مسار المورد المضمن.ResPathعادةً ما يستهدف المجلد الفرعيimagesالخاص به، دون/البادئ —'doconut-res/images'مع البادئة الافتراضية. كانResPathالفارغ صحيحًا في المكتبة السابقة، حيث كانت الموارد تأتي من جذر التطبيق؛ إنه غير صحيح هنا، ويتسبب في فشل دون خطأ.ExtractHyperlinksيجب أن يكون مفعلاً في تكوين تنسيق الخادم قبل أن يتمكنshowHyperlinksمن عرض أي شيء.
هل كانت هذه الصفحة مفيدة؟