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