Rychlý start

Tento návod provede aplikaci ASP.NET Core od prázdného Program.cs až po dokument vykreslený v prohlížeči: registraci serveru, kompletní balíček Vieweru (panel nástrojů Vieweru, připojení Vieweru a volitelné pásky Vyhledávání/Anotace), odkazy na prostředky, inicializaci klienta, otevření dokumentu a spuštění.

Nastavení serveru

AddDoconut() registruje služby; UseDoconutResources() a UseDoconut() zapojují middleware. Volání zdrojů musí být první. Volání sezení jsou také vyžadována — výchozí zabezpečení dokumentu Doconut ověřuje každý požadavek na stránku vůči stavu ASP.NET sezení. Už jste během Instalace registrovali Doconut? Přeskočte na další sekci.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddSession(); // Doconut document security rides on ASP.NET session state

app.UseSession();          // call UseSession() before UseDoconut()
app.UseDoconutResources(); // must be registered before UseDoconut()
app.UseDoconut();

Pro produkční rozvržení cest mapujte middleware dokumentu na explicitní větev a udržujte čtyři nastavení cest v souladu:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "Doconut.Viewer.lic");
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});
builder.Services.AddSession();

app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());

MiddlewarePath je koordinační hodnota; sama o sobě neprovádí mapování větve ASP.NET Core. V tomto příkladu host mapuje /doconut, takže klient musí použít BasePath: '/doconut'. ResourcesPath slouží k poskytování zabudovaného balíčku na /doconut-res a cesta k obrázkům widgetu je tedy ResPath: '/doconut-res/images'.

Přidání prohlížeče na stránku

Viewer je povinnou součástí stránky. Jeho vykreslovací plocha používá dva vnořené div elementy:

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

Považujte panel nástrojů, moduly připojení a plochu Vieweru za jednu stránkovou kompozici. Vyhledávání a Anotace vkládají své zabudované pásky do volitelných připojení, ale tyto moduly nikdy neexistují samostatně: vždy se připojují k Vieweru na stejné stránce. Použijte stejný pořádek jako v Doconut.TestApp a Doconut.TestApp.Distributed:

<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer navigation, zoom, Search, and Annotation buttons -->
</nav>

<div id="searchBarMount"></div>
<div id="annBarMount"></div>

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

Odkazování na prostředky prohlížeče

V Razor pohledu injektovaná služba Viewer vypisuje <link> a <script> značky vieweru v závislém pořadí — widget je jQuery plugin, takže jQuery musí být načteno před skripty vieweru:

@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
}))

Pro kompletní balíček Vieweru požádejte o zdroje Vieweru a modulů najednou:

@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 a IncludeViewerScripts jsou povinné jádrové příznaky. Nikdy nepublikujte příklad pásky Vyhledávání nebo Anotace bez nich, bez připojení Vieweru a instance docViewer. ReferenceCss a ReferenceScripts vynechají prostředky volitelného modulu, pokud aktuální licence tuto schopnost nepovoluje; jádro Vieweru se i tak spustí.

Inicializace prohlížeče

Klientský widget je jQuery plugin. Toto je minimální sada skutečných inicializačních možností (ne pseudokód):

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 () {
        // pages are visible; safe to hide a loading spinner here
    },
    // Forward annotation lifecycle events to the embedded ribbon when it is present.
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Zápis možností je skutečně smíšený — showThumbs, autoLoad a pageZoom jsou camelCase, ale FitType, BasePath a ResPath jsou PascalCase. Neexistuje jednotné pravidlo; pokud zadáte nesprávný zápis, volba je tiše ignorována (widget se vrátí k výchozímu nastavení místo vyhození chyby).

Sestavení kompletního balíčku Viewer

Obě referenční aplikace .NET 6 instalují následující části společně na jedné stránce:

Ačkoli hlavní panel nástrojů Vieweru je host markup, je instalován spolu s Viewerem a nesmí být dokumentován jako izolovaná kontrola. To zachovává jeho rozvržení, popisky, ikony a autorizační pravidla pod kontrolou vaší aplikace, zatímco každé tlačítko ovládá stejnou instanci Vieweru:

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

Úplný referenční panel nástrojů také kopíruje wwwroot/js/viewerToolbar.js do host aplikace pro ovládání rotace, miniatur, tisku, režimu celé obrazovky, rozvržení a pomocníků stavů tlačítek. Načtěte tento host soubor po Viewer.ReferenceScripts(...). Udržujte pomocníka a jeho <nav id="toolbar"> markup společně při kopírování kompletní ukázkové implementace.

Udržujte pořadí inicializace balíčku použité oběma referenčními aplikacemi:

1. Vypište CSS pro Viewer a licencované moduly.
2. Vykreslete panel nástrojů Vieweru, připojení Vyhledávání/Anotací a připojení Vieweru společně.
3. Vypište skripty pro Viewer a licencované moduly.
4. Načtěte viewerToolbar.js host aplikace.
5. Inicializujte docViewer a uchovejte vzniklý objViewer.
6. Inicializujte každou licencovanou pásku Vyhledávání nebo Anotace.
7. Zavolejte attach(objViewer) na každou pásku.
8. Otevřete dokument a uchovejte jeho token pro požadavky Vieweru a modulů.

Doconut.TestApp.Distributed zachovává tuto přesnou UI kompozici a stejný pomocník panelu nástrojů Vieweru. Jeho další hodnota požadavku access a nastavení asynchronního opakování vykreslování patří k distribuovanému přenosu; nemění způsob, jakým jsou Viewer, panel nástrojů nebo pásky sestaveny.

Serverové ochrany jsou důležité: když je volitelná schopnost nedostupná, její skript není vypuštěn, takže její jQuery plug‑in funkce neexistuje.

<script>
    let currentToken = '';

    const refitViewer = () =>
        requestAnimationFrame(() => objViewer.Refit());

    @if (Viewer.IsSearchEnabled)
    {
        <text>
    searchBar = $('#searchBarMount').doconutSearchBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token: currentToken }),
        onLayout: refitViewer
    });
    searchBar.attach(objViewer);
        </text>
    }

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token: currentToken }),
        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>

Oba vložené komponenty generují vlastní DOM pásky. Vyhledávání obsahuje skupiny Najít, Možnosti a Výsledky. Anotace obsahuje nástroje pro tvorbu, ovládání stylu, akce uložení a volitelné exportní/obrázkové akce. Pásky poskytují open(), close(), reset() a isOpen(); vždy po jejich vytvoření jednou zavolejte attach(objViewer).

Ukázka výše vynechává volitelné host callbacky a koncové body exportu/obrázku Anotace, aby byl start co nejmenší. Viz Vyhledávání a Anotace pro kompletní nastavení specifické pro funkci, nebo Vlastní motivy pro stylování nebo nahrazení panelu nástrojů Vieweru, který vlastní host.

Otevření dokumentu

Serverová strana je jeden endpoint: injektovaná služba Viewer otevře dokument a vrátí token sezení.

app.MapPost("/api/open", async (Viewer viewer) =>
{
    // The token is opaque — hand it to the widget, never log or persist it.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Klient získá tento token a předá ho widgetu pomocí objViewer.View(token):

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

Uzavření dokumentu

Zavolejte objViewer.Close() když uživatel opustí prohlížeč nebo otevře náhradní dokument. V server‑řízených pracovních tocích viewer.CloseDocument(token) okamžitě odstraní kešované sezení, uvolní vykreslovací engine, smaže bezpečnostní značku a odvolá token. Posuvná expirace provádí stejný úklid, ale explicitní uzavření se doporučuje u velkých dokumentů.

Dokončený tok požadavků je:

AddDoconut + middleware
    -> render CSS/scripts and mount div
    -> initialize docViewer
    -> OpenDocumentAsync
    -> return opaque token
    -> objViewer.View(token)
    -> page/search/annotation requests
    -> Close / CloseDocument

Považujte token za přístupový token (bearer credential): nikdy jej nelogujte, nikdy neukládejte, předávejte jej pouze widgetu. Identifikuje aktivní relaci dokumentu na serveru a přestane fungovat, když tato relace vyprší — dokument znovu otevřete, abyste získali nový.

Spusťte to

Umístěte PDF do wwwroot/files/Sample.pdf, spusťte dotnet run a otevřete stránku, která hostuje widget. První stránka se vykreslí v prohlížeči s panelem miniatur vlevo. Pokud se tak nestane, podívejte se na Řešení problémů.

Co získáte bez licence

Chybějící licence nevyvolá výjimku. Prohlížeč se vykreslí normálně, ale každá stránka nese vodoznak hodnocení. Viz Nastavení licence pro to, jak Doconut najde licenci a co se změní, až ji najde.