ViewerConfig – Doconut תיעוד

ViewerConfig (namespace Doconut) מתאר את המראה וההתנהגות של מציג הדפדפן. הוא אינו משפיע על איכות רינדור המסמך; השתמש בתצורת פורמט עבור זאת. מחלקת C# ותוסף JavaScript הישן имеют ערכי ברירת מחדל שונים, ולכן יש למפות ערכים במפורש.

מאפייני 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` בשורש האתר. עבור יישום בתיקייה וירטואלית, השתמש בשם התיקייה בלי סלאש מוביל `/` (`"myapp"` משמעותו `/myapp/DocImage.axd`).
`string`	`ResPath`	`"doconut-res/images"`	תיקייה שהווידג'ט טוען ממנה את התמונות שלו: תיקיית `images` תחת `ResourcesPath`, בלי סלאש מוביל `/`.
`string`	`FitType`	`"width"`	`"width"`, `"height"`, או ריק ללא התאמה אוטומטית. `"page"` אינו מתקבל על ידי הווידג'ט הנוכחי.
`bool`	`RetryOn409`	`false`	מנסה מחדש בקשות דף שמחזירות "still rendering". `DocImage.axd` מרנדר באופן סינכרוני ולעולם לא שולח אות זה; השאר `false`.

csharp

var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "/",                 // "/" = המטפל DocImage.axd בשורש האתר (Web.config)
    ResPath = "doconut-res/images", // תיקיית התמונות תחת ResourcesPath, ללא סלאש מוביל '/'
    ShowHyperlinks = true
};
// הפקודה: viewer.RenderViewer("viewerEl", token, config) – ראה את תיעוד ה-Viewer.

יצירת ViewerConfig עם RenderViewer

Viewer.RenderViewer(elementId, token, config) ממיר ViewerConfig לסקריפט האתחול של הווידג'ט. הוא כותב שישה מהמאפיינים שלמעלה — BasePath, ResPath, ShowThumbs, AutoLoad, PageZoom, ו-FitType — ואז קורא ל-View(token). שאר המאפיינים אינם נכתבים: עבור MaxZoom, ShowHyperlinks, הגדרות הזום, או כל קריאה חוזרת, אתחל את הווידג'ט בעצמך עם אפשרויות ה-JavaScript למטה. ראה מציג עבור RenderViewer.

מיפוי 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`	ה‑`maxZoom` של JavaScript שונה מ‑C# (`300`).
`showToolTip` / `toolTipPageText`	`true` / `"Page "`	תיאור מקף למיקום העמוד.
`format` / `doc` / `AccessToken`	`""` / `0` / `""`	ערכי אתחול פנימיים; בדרך כלל ממולאים על‑ידי `View(token)`.
`debugMode`	`false`	אבחון לקוח נוסף.
`FitType`	`""`	אין התאמה אוטומטית אלא אם נמסר ערך.
`BasePath`	`"DocImage.axd"`	ברירת מחדל ישנה. הגדר במפורש: `'/'` למטפל בשורש האתר.
`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: '/',
    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	ממשק ההערות נסגר.

שמרו על קריאות חוזרות מהירות; שלחו טלמטוריה באופן אסינכרוני ואל תחסמו את רינדור העמוד.

קבוצות שיטות ציבוריות

קבוצה	שיטות נפוצות
Lifecycle	`View(token, accessToken?)`, `Close(server?)`, `Token()`, `Init()`, `IsLoaded()`
Navigation	`GotoPage(page)`, `ShowPage(page, focus?)`, `Next(next)`, `CurrentPage()`, `TotalPages()`
Zoom and fit	`Zoom(zoomIn)`, `CurrentZoom()`, `FitType(value)`, `Refit()`
Orientation	`Rotate(page, angle)`, `Flip(page, flipType)`
Thumbnails	`HideThumbs(hide)`, `ThumbSize(size)`, `ReloadThumbs(width)`, `ScrollToThumb(thumb)`
Search	`CanSearch()`, `Search(...)`, `SearchMatchCount()`, `SearchSummary(...)`, `GotoSearchMatch(...)`
Annotation	`SaveAnnotations()`, `GetAnnotations()`, `PushAnnotations(...)`, `CloseAnnotations(...)`, `ShowAnnotations(...)`
Copy	`Copy(...)`, `CopyPage(pageNumber)`, `CopyMode(enabled)`

קובץ ה‑JavaScript מכיל גם עוזרים פנימיים. התייחסו רק לשיטות המשמשות בממשק המשתמש הרפרנסי ומתועדות כאן או במדריכי הפיצ'רים כנקודות אינטגרציה יציבות.

אפשרויות ניסיון חוזר

הווידג'ט גם מקבל retryOn409 ואת הגדרות האחזור שלו (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs). הן משמשות פריסות שדפים שלהם נוצרות ברקע. DocImage.axd מציג כל דף במהלך הבקשה, ולכן יש להשאיר את retryOn409 כבוי.

רשימת בדיקת נתיב

BasePath הוא '/' כאשר המטפל DocImage.axd נמצא בשורש האתר — מאפיין path של המטפל ב-Web.config מחליט היכן הוא מגיב. במאגר וירטואלי, השתמש בשם הספרייה ללא סלאש מוביל / ('myapp', ולא '/myapp': הצופה מוסיף את הסלאש, ו-//myapp/... הוא בקשה למארח אחר).
DoconutOptions.ResourcesPath הוא המקום שבו מודול המשאבים מגיש את הקבצים המוטמעים (/doconut-res כברירת מחדל).
ResPath מצביע על תת-התיקייה images שלו, גם ללא סלאש מוביל / ('doconut-res/images'). הפנייה אל 'doconut-res' גורמת לכל האיקונים לקבל 404 בעוד שהמסמך עדיין מוצג.
ב‑MVC, routes.IgnoreRoute("doconut-res/{*pathInfo}") חייב לבוא אחרי ResourcesPath אם אתה משנה אותו.
ExtractHyperlinks חייב להיות מופעל בתצורת פורמט השרת לפני ש-showHyperlinks יכול להציג משהו.