התחלה מהירה
הצג את המסמך הראשון שלך בתוך דקות
מדריך זה לוקח אפליקציית ASP.NET Core מריק Program.cs למסמך שמוצג בדפדפן: רישום השרת, חבילת הצופה המלאה (סרגל כלי הצופה, הרכבת הצופה, ורצועות חיפוש/הערות אופציונליות), הפניות נכסים, אתחול הלקוח, פתיחת המסמך והפעלה.
הגדרת שרת
AddDoconut() רושמת את השירותים; UseDoconutResources() ו-UseDoconut() מחברים את המידלוור. קריאת המשאבים חייבת לבוא ראשונה. UseDoconut() משיבה לכל בקשה שמגיעה אליה, ולכן יש להרכיב אותה בענף משלה עם app.Map. קריאות הסשן נדרשות גם הן — האבטחה המוגדרת של Doconut מאמתת כל בקשת עמוד מול מצב הסשן של ASP.NET. מצב הסשן דורש מטמון: AddDistributedMemoryCache() מספק אחד. אפליקציית MVC או Razor Pages כבר רושמת אותו, אך אפליקציית minimal-API לא עושה זאת, ובלי זה האפליקציה נעצרת בהפעלה עם Unable to resolve service for type 'IDistributedCache'. כבר רשמת את Doconut במהלך התקנה? עבור הלאה לחלק הבא.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // מצב סשן צריך מטמון (MVC/Razor Pages כבר מוסיפים אחד)
builder.Services.AddSession(); // אבטחת המסמך של Doconut מתבססת על מצב סשן של ASP.NET
app.UseSession(); // קרא UseSession() לפני UseDoconut()
app.UseDoconutResources(); // חייב להירשם לפני UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());עבור פריסת נתיבים בסגנון ייצור, מפת את המידלוור של המסמך לענף מפורש ושמור על ארבעת הגדרות הנתיב מיושרות:
builder.Services.AddDoconut(options =>
{
options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
options.MiddlewarePath = "/doconut";
options.ResourcesPath = "/doconut-res";
options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());MiddlewarePath הוא ערך תיאום; הוא לא ממפה ענף של ASP.NET Core בעצמו. בדוגמה זו המארח ממפה /doconut, ולכן הלקוח משתמש ב-BasePath: 'doconut'. ResourcesPath מגישה את החבילה המשובצת ב-/doconut-res, ולכן נתיב משאב התמונה של הווידג'ט הוא ResPath: 'doconut-res/images'. כתבו את שניהם בלי קו נטוי מוביל: הצופה מוסיף אחד בעצמו, ולכן '/doconut' יהפוך ל-//doconut/DocImage.axd, שהדפדפן קורא זאת כבקשה למארח בשם doconut, והצופה נכשל עם "The viewer handler could not be reached".
הוסף את הצופה לעמוד
הצופה הוא הליבה הנדרשת של העמוד. משטח הרינדור שלו משתמש בשני divים מקוננים:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>התייחס לסרגל הכלים, הרכבות המודול ומשטח הצופה כקומפוזיציית עמוד אחת. חיפוש ו הערות מכניסים את הרצועות המשובצות שלהם למקומות האופציונליים, אך מודולים אלה אף פעם אינם עומדים לבד: הם תמיד מצורפים לצופה באותו העמוד. השתמש בסדר זה:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- כפתורי ניווט, זום, חיפוש והערות של Viewer -->
</nav>
<div id="searchBarMount"></div>
<div id="annBarMount"></div>
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>הפנה לנכסי הצופה
בתצוגת Razor, השירות המוזרק Viewer פולט את תגיות <link> ו-<script> של הצופה בסדר תלות — הווידג'ט הוא תוסף jQuery, ולכן יש לטעון את jQuery לפני סקריפטי הצופה:
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true
}))עבור חבילת הצופה המלאה, בקש את משאבי הצופה והמודול יחד:
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true,
IncludeSearchCss = true,
IncludeAnnotationCss = true
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true,
IncludeSearchScripts = true,
IncludeSearchBar = true,
IncludeAnnotationScripts = true,
IncludeAnnotationBar = true
}))IncludeViewerCss ו-IncludeViewerScripts הם דגלי הליבה המחויבים. לעולם אל תפרסם דוגמת רצועת חיפוש או הערות ללא הם, הרכבת הצופה, ומופע של docViewer. ReferenceCss ו-ReferenceScripts משמיטות משאבי מודול אופציונלי כאשר
הרישיון הנוכחי אינו מעניק את היכולת; הצופה הליבה עדיין מתחיל.
אתחול הצופה
הווידג'ט בצד הלקוח הוא תוסף jQuery. זהו סט מינימלי של אפשרויות אתחול אמיתיות (לא קוד מדומה):
let searchBar = null;
let annBar = null;
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: 'doconut', // אין קו נטוי מוביל '/'
ResPath: 'doconut-res/images', // אין קו נטוי מוביל '/'
onViewerReady: function () {
// הדפים נראים; בטוח להסתיר כאן את סמן הטעינה
},
// העבר אירועי מחזור החיים של ההערה לריבון המוטמע כאשר הוא קיים.
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});הקידוד של האפשרויות הוא באמת מעורב — showThumbs, autoLoad, ו-pageZoom הם camelCase, אך FitType, BasePath, ו-ResPath הם PascalCase. אין כלל עקבי; אם מקודדים בצורה שגויה, האפשרות מתעלמת בשקט (הווידג'ט חוזר לברירת המחדל במקום לזרוק שגיאה).
ארבעה פרטים נוספים נכשלים ללא הודעת שגיאה:
BasePathאין סלאש מוביל.'doconut'מבקש/doconut/DocImage.axd;'/doconut'מייצר//doconut/DocImage.axd, שהדפדפן קורא אותו כבקשה למארח אחר.ResPath: 'doconut-res/images'— האיקונים נמצאים בתיקייה אחת מתחת לשורש המשאבים. עם'doconut-res', כל אייקון מחזיר 404: אין סמלים בסרגל הכלים ואין ספינר טעינה, בעוד שהמסמך עצמו עדיין מוצג. סלאש מוביל שובר זאת באותו אופן כמוBasePath.- Callbacks הם אפשרויות.
onViewerReady,onErrorוהאחרים נכנסים לאובייקט שמועבר ל-docViewer(...). פונקציה גלובלית בשם הצופה, כגוןctlDoc_ViewerReady, לעולם לא נקראת. - שמרו את הצופה, ואז קראו ל-
Viewבנפרד.docViewer(...)מחזיר את האובייקט עםZoom,Nextו-FitType;View(...)מחזיר משהו אחר.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)מציג את המסמך, ואז נכשל עםobjViewer.Zoom is not a functionבלחיצה הראשונה על סרגל הכלים.
הרכבת חבילת הצופה המלאה
דף צופה מלא מתקין את החלקים הבאים יחד:
| חלק מהחבילה | דרישה | איך זה מחובר |
|---|---|---|
משאבי הצופה, הרכבה, ו-objViewer | נדרש | רינדור מסמך ליבה |
| סרגל כלים של הצופה | נדרש לדף מלא | סימון מארח; כפתורים קוראים לאותו objViewer |
| סרט ריבון חיפוש | אופציונלי, מודול מורשה | doconutSearchBar(...).attach(objViewer) |
| סרט ריבון הערות | אופציונלי, מודול מורשה | doconutAnnotationBar(...).attach(objViewer) |
למרות שסרגל הכלים הראשי של הצופה הוא סימון מארח, הוא מותקן לצד הצופה ולעולם אין לתעד אותו כבקר מבודד. זה שומר על הפריסה, התוויות, האיקונים, וכללי האימות תחת שליטת היישום שלך בעוד שכל כפתור מניע את אותה מופע של הצופה:
<nav id="toolbar" aria-label="Document viewer controls">
<button type="button" onclick="objViewer.GotoPage(1)">First</button>
<button type="button" onclick="objViewer.Next(false)">Previous</button>
<button type="button" onclick="objViewer.Next(true)">Next</button>
<button type="button" onclick="objViewer.GotoPage(objViewer.TotalPages())">Last</button>
<button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
<button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
<button type="button" onclick="objViewer.FitType('width')">Fit width</button>
<button type="button" onclick="objViewer.FitType('height')">Fit height</button>
<button type="button" id="openSearch">Search</button>
<button type="button" id="openAnnotations">Annotations</button>
</nav>עזרים לסיבוב, תצוגה מקדימה, הדפסה, מסך מלא, פריסה, ומצב כפתור שייכים לסקריפט סרגל הכלים שלכם, שקורא לאותו objViewer. טענו אותו אחרי Viewer.ReferenceScripts(...), ושמרו אותו יחד עם סימון ה-<nav id="toolbar"> שלו.
שמרו על סדר האתחול הבא:
- הפיצו CSS עבור הצופה והמודולים המורשים.
- הציגו את סרגל הכלים של הצופה, הרכבות חיפוש/הערות, והרכבת הצופה יחד.
- הפיצו סקריפטים עבור הצופה והמודולים המורשים.
- טענו את סקריפט העזר של סרגל הכלים של היישום המארח.
- אתחלו את
docViewerושמרו אתobjViewerשהתקבל. - אתחלו כל סרט ריבון חיפוש או הערות מורשה.
- קראו ל-
attach(objViewer)על כל ריבון. - פתחו את המסמך ושמרו את האסימון שלו לבקשות הצופה והמודול.
בפריסה מבוזרת, ערך הבקשה הנוסף access והגדרות הניסיון החוזר של רינדור אסינכרוני שייכים לתחבורה; הם אינם משנים את האופן שבו הצופה, סרגל הכלים או הריבונים מורכבים.
הגנות בצד השרת חשובות: כאשר יכולת אופציונלית אינה זמינה, הסקריפט שלה אינו מפוצץ, ולכן פונקציית תוסף ה-jQuery שלה אינה קיימת.
<script>
let token = '';
const refitViewer = () =>
requestAnimationFrame(() => objViewer.Refit());
@if (Viewer.IsSearchEnabled)
{
<text>
searchBar = $('#searchBarMount').doconutSearchBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token }),
onLayout: refitViewer
});
searchBar.attach(objViewer);
</text>
}
@if (Viewer.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token }),
onLayout: refitViewer
});
annBar.attach(objViewer);
</text>
}
document.getElementById('openSearch').addEventListener('click', () => {
if (!searchBar) return;
searchBar.isOpen() ? searchBar.close() : searchBar.open();
});
document.getElementById('openAnnotations').addEventListener('click', () => {
if (!annBar) return;
annBar.isOpen() ? annBar.close() : annBar.open();
});
</script>שני הרכיבים המוטמעים מייצרים את ה-DOM של הריבון שלהם. חיפוש מכיל קבוצות מציאה, אפשרויות, ותוצאות. הערות מכילות את כלי הכתיבה, בקרות סגנון, פעולות שמירה, ופעולות ייצוא/תמונה אופציונליות. הסרגלים חושפים את open(), close(), reset(), ו-isOpen(); תמיד קראו ל-attach(objViewer) פעם אחת לאחר יצירתם.
הדוגמה למעלה משאירה ללא קריאות חזרה של המארח וכתובות קצה של ייצוא/תמונה של הערות כדי לשמור על אתחול מינימלי. ראו חיפוש ו-הערות עבור ההגדרה המלאה של תכונה ספציפית, או ערכות נושא מותאמות כדי לעצב או להחליף את סרגל הכלים של הצופה שבבעלות המארח.
פתח מסמך
צד השרת הוא נקודת קצה אחת: השירות המוזרק Viewer פותח את המסמך ומחזיר אסימון סשן.
app.MapPost("/api/open", async (Viewer viewer) =>
{
// הטוקן הוא אטום — העבר אותו ל‑ווידג'ט, אל תתעד או תשמר אותו.
string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});הלקוח מאחזר את האסימון הזה ומעביר אותו לווידג'ט עם objViewer.View(token):
fetch('/api/open', { method: 'POST' })
.then(resp => resp.json())
.then(data => {
token = data.token;
objViewer.View(token);
});סגור את המסמך
קרא objViewer.Close(true) כאשר המשתמש עוזב את הצופה או פותח מסמך חלופי: הוא מנקה את הווידג'ט ושולח בקשת סגירה לשרת. objViewer.Close() ללא ארגומנט מנקה רק את הווידג'ט. בזרימות עבודה שמונחות על ידי השרת, viewer.CloseDocument(token) מסיר מיידית את הסשן המוטמן, משחרר את מנוע הרינדור, מוחק את סימן האבטחה שלו, ומבטל את האסימון. פג תוקף מתחלף מבצע בסופו של דבר את אותה ניקוי, אך סגירה מפורשת מומלצת למסמכים גדולים.
זרימת הבקשה המלאה היא:
AddDoconut + middleware
-> render CSS/scripts and mount div
-> initialize docViewer
-> OpenDocumentAsync
-> return opaque token
-> objViewer.View(token)
-> page/search/annotation requests
-> Close / CloseDocumentהתייחס לאסימון כמו לאישור נושא: אל תתעד אותו, אל תשמר אותו, העבר אותו רק לווידג'ט. הוא מזהה סשן מסמך חי בשרת ומפסיק לעבוד כאשר הסשן פג — פתח מחדש את המסמך כדי לקבל אחד חדש.
הפעל את זה
הציב קובץ PDF בwwwroot/files/Sample.pdf, הפעל dotnet run, ופתח את העמוד שמארח את הווידג'ט. העמוד הראשון מוצג בצופה, עם לוח תמונות ממוזערות בצד שמאל. אם זה לא קורה, ראה פתרון בעיות.
מה אתה מקבל ללא רישיון
חוסר רישיון אינו גורם לשגיאה. הצופה מציג כרגיל, אך כל עמוד נושא סימן מים של הערכה. ראה הגדרת רישיון כדי להבין איך Doconut מוצא רישיון ומה משתנה לאחר מכן.
האם דף זה היה מועיל?