התחלה מהירה
הצגת המסמך הראשון שלך בתוך דקות
המדריך הזה מעביר אפליקציית ASP.NET Core מריק Program.cs למסמך המוצג בדפדפן: רישום השרת, חבילת הצופה המלאה (סרגל כלים של הצופה, הרכבת הצופה, ורצועות חיפוש/הערה אופציונליות), הפניות נכסים, אתחול הלקוח, פתיחת המסמך והפעלה.
הגדרת השרת
AddDoconut() רושמת את השירותים; UseDoconutResources() ו-UseDoconut() מחברים את ה‑middleware. קריאת המשאבים חייבת לבוא ראשונה. 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());כדי לקבל פריסת נתיבים בסגנון ייצור, מפתים את middleware של המסמך לענף מפורש ושומרים על ארבעת הגדרות הנתיב מיושרות:
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".
הוספת הצופה לעמוד
הצופה הוא הליבה הדרושה של העמוד. משטח הרינדור שלו משתמש בשניים מקוננים של divs:
<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) =>
{
// הטוקן הוא אטום — העבר אותו ל‑widget, אל תתעד או תשמר אותו.
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 מוצא רישיון ומה משתנה לאחר מכן.
האם דף זה היה מועיל?