התחלה מהירה

הצגת המסמך הראשון שלך בתוך דקות

מדריך זה מעביר אפליקציית ASP.NET Core מריק Program.cs למסמך המוצג בדפדפן: רישום השרת, חבילת הצופה המלאה (סרגל כלים של הצופה, הרכבה של הצופה, ורצועות חיפוש/הערות אופציונליות), הפניות נכסים, אתחול הלקוח, פתיחת המסמך והפעלה.

היישום המארח חייב למקד זמן ריצה שתומך ב‑netstandard2.1 — .NET Core 3.0 או גרסה מאוחרת יותר.

Server setup

AddDoconut() רושמת את השירותים; UseDoconutResources() ו‑UseDoconut() מחברים את המידלוור. קריאת המשאבים חייבת לבוא ראשונה. UseDoconut() משיבה על כל בקשה שמגיעה אליה, ולכן יש להרכיב אותה בענף משלה עם app.Map. קריאות הסשן נדרשות גם הן — האבטחה המוגדרת של Doconut מאמתת כל בקשת עמוד מול מצב הסשן של ASP.NET. מצב הסשן דורש מטמון: AddDistributedMemoryCache() מספק אחד. אפליקציית MVC או Razor Pages כבר רושמת אותו, אך אפליקציית minimal‑API לא עושה זאת, וללא זה האפליקציה נעצרת בעת ההפעלה עם Unable to resolve service for type 'IDistributedCache'. כבר רשמת את Doconut במהלך התקנה? עבור הלאה לסעיף הבא.

csharp
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());

הגדרה זו שומרת על צורת הבקשה ההיסטורית של DocImage.axd ומרכיבה את המידלוור של המסמך בענף תואם. זהו הסידור שיש להעתיק כאשר אתם ממשיכים עם אפליקציית .NET Standard קיימת, מכיוון שהלקוח ממשיך לקרוא לאותו URL שהוא תמיד השתמש בו:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // השאר את בדיקת הסשן של Doconut מופעלת
    options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // מצב הסשן צריך מטמון (MVC/Razor Pages כבר מוסיפים אחד)
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromSeconds(3600);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
});

// נדרש לקידודים מרובי בתים בכמה פורמטים של מסמכים.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();   // BEFORE ענף המסמך
app.MapWhen(
    context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconut() אינו מקבל אפשרויות בגרסה זו — הכל הועבר ל‑AddDoconut(). MiddlewarePath הוא ערך תיאום; הוא אינו ממפה ענף של ASP.NET Core בעצמו. עם ענף DocImage.axd למעלה, הלקוח משתמש ב‑BasePath: '/'; עם app.Map("/doconut", ...) מההגדרה המינימלית, הוא משתמש ב‑BasePath: 'doconut'. ResourcesPath מגישה את החבילה המוטמעת ב‑/doconut-res, ולכן נתיב משאב התמונה של הווידג'ט הוא ResPath: 'doconut-res/images'.

Add the viewer to a page

ה-Viewer הוא הליבה הדרושה של העמוד. משטח הרינדור שלו משתמש בשניים מקוננים של divs:

html
<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

התייחסו לסרגל הכלים, הרכבות המודול, ומשטח ה-Viewer כקומפוזיציה של עמוד אחד. חיפוש ו הערות משיקים את הרצועות המוטמעות שלהם למקומות אופציונליים, אך המודולים הללו אף פעם אינם עצמאיים: הם תמיד מצורפים ל‑Viewer באותו העמוד.

html
<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>

הפנייה למקורות הצופה

ב‑view של Razor, השירות המוזרק Viewer פולט את תגיות <link> ו‑<script> של הצופה בסדר תלות — הווידג'ט הוא תוסף jQuery, ולכן יש לטעון את jQuery לפני סקריפטי הצופה:

html
@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
@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 משמיטים משאבי מודול אופציונלי כאשר הרישיון הנוכחי אינו מעניק את היכולת; ליבת הצופה עדיין מתחילה.

קריאות אלו מחליפות קבצי סקריפט שהועתקו ידנית. אם היישום עדיין טוען את שלו docViewer.js, documentLinks.js, או docViewer.UI.js, הסר את התגיות האלו ברגע שהדף פועל מהמשאבים שהופקו — ראה את מדריך ההגירה.

אתחול הצופה

הווידג'ט בצד הלקוח הוא תוסף jQuery. זהו סט מינימלי של אפשרויות אתחול אמיתיות (לא קוד מדומה):

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // הענף DocImage.axd; 'doconut' עם app.Map("/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);
    }
});

ארבעה פרטים קובעים האם דף זה יעבוד בכלל:

  • Callbacks הם אפשרויות. onViewerReady, onViewerBusy, onCopy, ו‑ onAutoLoadStatus מועברים באובייקט האפשרויות. הצופה הקודם ייצר שמות פונקציות גלובליות מה‑id של המכולה וקרא להם; זה אינו עושה זאת. מטפל שהוגדר רק כפונקציה גלובלית לעולם לא רץ, ואין שום דיווח.
  • ResPath מצביע על קידומת המשאבים, ולא על שורש היישום. עם ברירת המחדל ResourcesPath, הערך הוא doconut-res/images. אם שינית את ResourcesPath, השתמש בקידומת שלך במקום זאת. האיקונים ממוקמים תיקייה אחת מתחת לשורש המשאבים: עם 'doconut-res', כל אייקון מחזיר 404 בעוד שהמסמך עצמו עדיין מוצג.
  • BasePath אין סלאש מוביל מלבד ערך שורש האתר '/'. 'doconut' מבקש את /doconut/DocImage.axd; '/doconut' מייצר //doconut/DocImage.axd, ש‑ הדפדפן קורא זאת כבקשה למארח אחר.
  • שמור את הצופה, ואז קרא View בנפרד. docViewer(...) מחזיר את האובייקט עם Zoom, Next ו‑FitType; View(...) מחזיר משהו אחר. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) מציג את המסמך, ואז נכשל עם objViewer.Zoom is not a function בלחיצה הראשונה על סרגל הכלים.

כל אלה נכשלות בשקט — ראה את פתרון בעיות ואת מדריך ההגירה.

הכתיב של האפשרויות מעורב באמת — showThumbs, autoLoad ו‑pageZoom הם camelCase, אך FitType, BasePath ו‑ResPath הם PascalCase. אין כלל עקבי; אם תכתוב את הכתיב בצורה שגויה, האופציה תתעלם בשקט (הווידג'ט יחזור לערך ברירת המחדל במקום לזרוק שגיאה).

הרכבת חבילת Viewer המלאה

דף Viewer מלא מתקין את החלקים הבאים יחד:

חלק מהחבילהדרישהאיך הוא מחובר
משאבי Viewer, הרכבה, וobjViewerנדרשמעבד מסמכים מרכזי
סרגל כלי Viewerנדרש לדף מלאסימון מארח; כפתורים קוראים לאותו objViewer
סרגל חיפושאופציונלי, מודול מורשהdoconutSearchBar(...).attach(objViewer)
סרגל הערותאופציונלי, מודול מורשהdoconutAnnotationBar(...).attach(objViewer)

למרות שסרגל הכלים הראשי של Viewer הוא סימון מארח, הוא מותקן לצד ה-Viewer ולעולם אין לתעד אותו כפקד מבודד. כך נשמרים הפריסה, התוויות, האייקונים, וכללי האימות תחת שליטת היישום שלך בעוד שכל כפתור מניע את אותה מופע Viewer:

html
<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>

שמור על סדר האתחול הבא:

  1. הפץ CSS עבור ה-Viewer והמודולים המורשים.
  2. הצג את סרגל הכלים של Viewer, הרכבות חיפוש/הערות, והרכבת Viewer יחד.
  3. הפץ סקריפטים עבור ה-Viewer והמודולים המורשים.
  4. טען את סקריפט העזר של סרגל הכלים של יישום המארח.
  5. אתחל את docViewer ושמור את objViewer שהתקבל.
  6. אתחל כל סרגל חיפוש או הערות מורשה.
  7. קרא לattach(objViewer) על כל סרגל.
  8. פתח את המסמך ושמור את האסימון שלו לבקשות Viewer והמודול.

הגנות צד השרת חשובות: כאשר יכולת אופציונלית אינה זמינה, הסקריפט שלה אינו מופץ, ולכן פונקציית תוסף jQuery שלה אינה קיימת.

html
<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 שבבעלות המארח.

פתיחת מסמך

צד השרת הוא נקודת קצה אחת: השירות המוזרק Viewer פותח את המסמך ומחזיר אסימון סשן. הפתיחה אסינכרונית בגרסה זו.

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // הטוקן אינו גלוי — העבר אותו לווידג'ט, אל תתעד או תשמר אותו.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

הלקוח מקבל את האסימון הזה ומעביר אותו לווידג'ט עם objViewer.View(token):

javascript
fetch('/api/open', { method: 'POST' })
    .then(resp => resp.json())
    .then(data => {
        token = data.token;
        objViewer.View(token);
    });

אין צורך בחימום לפני הפתיחה הראשונה. אם אתה מעביר יישום קדימה, מחק כל קריאת InitCache() ואת הדגל המגן עליה — השיטה אינה קיימת יותר.

סגירת המסמך

התקשר ל-objViewer.Close(true) כאשר המשתמש עוזב את הצופה או פותח מסמך חלופי: הוא מנקה את הווידג'ט ושולח בקשת סגירה לשרת. objViewer.Close() ללא ארגומנט מנקה רק את הווידג'ט. בתהליכי עבודה מונעי‑שרת, viewer.CloseDocument(token) מסיר מיידית את הסשן המוטמן, משחרר את מנוע הרינדור, מוחק את סימן האבטחה שלו, ומבטל את האסימון. תפוגה מתגלגלת מבצעת בסופו של דבר את אותה ניקוי, אך סגירה מפורשת מומלצת למסמכים גדולים.

זרימת הבקשה המלאה היא:

text
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 מוצא רישיון ומה משתנה לאחר מכן.

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