Rychlý start

Tento průvodce provede aplikaci ASP.NET Core od prázdného Program.cs až po dokument vykreslený v prohlížeči: registrace serveru, kompletní balíček Viewer (panel nástrojů Vieweru, připojení Vieweru a volitelné pásy Vyhledávání/Anotací), odkazy na prostředky, inicializace 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í. Již jste během Instalace zaregistrovali 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ě nemapuje větev ASP.NET Core. V tomto příkladu host mapuje /doconut, takže klient musí použít BasePath: '/doconut'. ResourcesPath slouží k nasazení vložené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‑y:

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

Považujte panel nástrojů, montáže modulů a plochu Vieweru za jednu stránkovou kompozici. Vyhledávání a Anotace vkládají své vložené pásy do volitelných montáží, 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>

Odkaz na prostředky prohlížeče

V Razor view injektovaná služba Viewer vypisuje <link> a <script> tagy vieweru ve správném pořadí závislostí — 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 Viewer požádejte o prostředky 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é základní příznaky. Nikdy nepublikujte příklad pásu Vyhledávání nebo Anotací bez nich, bez připojení Vieweru a instance docViewer. ReferenceCss a ReferenceScripts vynechají prostředky volitelného modulu, pokud aktuální licence tuto funkci nepodporuje; základní Viewer se i tak spustí.

Inicializace prohlížeče

Klientský widget je jQuery plugin. Toto je minimální sada skutečných init 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, zatímco FitType, BasePath a ResPath jsou PascalCase. Neexistuje jednotné pravidlo; pokud zadáte nesprávný zápis, možnost bude 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 8 instalují následující části společně na jedné stránce:

Ačkoliv je hlavní panel nástrojů Vieweru hostitelský markup, je instalován spolu s Viewerem a nesmí být dokumentován jako izolovaný ovládací prvek. To udržuje 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 hostitelské aplikace pro ovládání rotace, miniatur, tisku, režimu celé obrazovky, rozvržení a stavových pomocníků tlačítek. Načtěte tento hostitelský soubor po Viewer.ReferenceScripts(...). Udržujte pomocníka a jeho <nav id="toolbar"> markup pohromadě při kopírování celé ukázkové implementace.

Udržujte pořadí inicializace balíčku, jak používají obě referenční aplikace:

1. Vypište prostředky Vieweru, Vyhledávání a Anotací najednou.
2. Vykreslete panel nástrojů Vieweru, montáže pásů a montáž Vieweru společně.
3. Inicializujte docViewer jako první.
4. Vytvořte každý licencovaný pás a připojte jej ke stejnému objViewer.
5. Otevřete dokument a uchovejte jeho token pro požadavky 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 transportu; nemění způsob, jakým jsou Viewer, panel nástrojů nebo pásy sestaveny.

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

<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ás. Vyhledávání obsahuje skupiny Find, Options a Results. Anotace obsahuje nástroje pro tvorbu, ovládání stylů, akce uložení a volitelné exportní/obrázkové akce. Pásy vystavují metody open(), close(), reset() a isOpen(); vždy po vytvoření jednou zavolejte attach(objViewer).

Ukázka výše vynechává volitelné hostitelské zpětné volání a koncové body exportu/obrázku Anotací, aby byl start co nejmenší. Viz Vyhledávání a Anotace pro kompletní nastavení konkrétních funkcí, nebo Vlastní motivy pro stylování či nahrazení hostitelského panelu Vieweru.

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í viewer nebo otevře náhradní dokument. V server‑řízených pracovních postupech viewer.CloseDocument(token) okamžitě odstraní kešovaný token, uvolní vykreslovací engine, smaže bezpečnostní značku a token zruší. Posuvná expirace provede stejný úklid později, ale explicitní zavření se doporučuje u velkých dokumentů.

Dokončený tok požadavků vypadá takto:

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

Token považujte za přístupové oprávnění: nikdy jej nelogujte, neukládejte a předávejte jej jen widgetu. Identifikuje aktivní sezení dokumentu na serveru a přestane fungovat, když sezení vyprší — otevřete dokument znovu a získáte nový token.

Spuštění

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í ve vieweru s panelovým náhledem 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. Viewer se vykreslí normálně, ale každá stránka bude obsahovat vodotisk s hodnocením. Viz Nastavení licence pro to, jak Doconut najde licenci a co se změní, až ji najde.