ViewerConfig

אפשרויות וידג'ט של מציג הלקוח

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" לפני)תיקיית התמונות שהווידג'ט טוען משלה: תיקיית 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

ברירות מחדל של JavaScript

לוידג'ט יש ברירות מחדל ישנות שמבדילות מהמחלקה ב‑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 הישנה. כאשר הוא מופעל, הווידג'ט מבצע סקר עם ערכי ברירת המחדל של JavaScript אלה:

אפשרותברירת מחדל
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 יכול להציג משהו.

האם דף זה היה מועיל?