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 Vieweru (panel nástrojů Vieweru, připojení Vieweru a volitelné pásky Vyhledávání/Anotace), 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í přijít jako první. Volání relace jsou také vyžadována — výchozí zabezpečení dokumentu Doconut ověřuje každý požadavek na stránku proti stavu relace ASP.NET. Stav relace potřebuje mezipaměť: AddDistributedMemoryCache() ji poskytuje. MVC nebo Razor Pages aplikace ji již registrují, ale minimální API aplikace ne, a bez ní se aplikace zastaví při spuštění s chybou Unable to resolve service for type 'IDistributedCache'. Již jste během Installation zaregistrovali Doconut? Přeskočte na další sekci.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // stav relace potřebuje mezipaměť (MVC/Razor Pages ji již přidávají)
builder.Services.AddSession(); // zabezpečení dokumentu Doconut využívá stav relace ASP.NET

app.UseSession();          // zavolejte UseSession() před UseDoconut()
app.UseDoconutResources(); // musí být zaregistrováno před UseDoconut()
app.UseDoconut();

Pro rozvržení cesty ve stylu produkce mapujte middleware dokumentu na explicitní větev a udržujte čtyři nastavení cesty zarovnaná:

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 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 používá BasePath: 'doconut'. ResourcesPath slouží k nasazení vloženého balíčku na /doconut-res a cesta k obrázku widgetu je tedy ResPath: 'doconut-res/images'. Zapište obojí bez úvodní lomítka: viewer si přidá vlastní, takže '/doconut' by se změnilo na //doconut/DocImage.axd, což prohlížeč interpretuje jako požadavek na hosta s názvem doconut, a viewer selže s chybou „The viewer handler could not be reached“.

Přidejte prohlížeč na stránku

Viewer je povinným jádrem stránky. Jeho vykreslovací plocha používá dva vnořené divy:

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

Považujte panel nástrojů, připojení modulů a povrch Vieweru za jednu stránkovou kompozici. Vyhledávání a Anotace vkládají své vložené pásky do volitelných připojení, ale tyto moduly nejsou nikdy samostatné: vždy se připojují k Vieweru na stejné stránce. Použijte stejný pořádek jako 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> značky prohlížeče 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 Vieweru požádejte o Viewer a prostředky 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ásky Vyhledávání nebo Anotace bez nich, připojení Vieweru a instance docViewer. ReferenceCss a ReferenceScripts vynechají prostředky volitelného modulu, pokud aktuální licence tuto schopnost nepovoluje; základní Viewer se i tak spustí.

Inicializace prohlížeče

Klientský widget je plugin jQuery. 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',             // bez úvodního '/'
    ResPath:    'doconut-res/images',  // bez úvodního '/'
    onViewerReady: function () {
        // stránky jsou viditelné; je bezpečné zde skrýt indikátor načítání
    },
    // Přeposlat události životního cyklu anotací do vložené lišty, pokud je přítomna.
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Volby mají skutečně smíšené psaní – showThumbs, autoLoad a pageZoom jsou camelCase, ale FitType, BasePath a ResPath jsou PascalCase. Neexistuje žádné konzistentní pravidlo; pokud napíšete nesprávně, volba je tiše ignorována (widget se vrátí k výchozímu nastavení místo vyhození chyby).

Sestavení kompletního balíčku Vieweru

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 hostovací markup, je instalován spolu s Viewerem a nikdy by neměl 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í lišta také kopíruje wwwroot/js/viewerToolbar.js do hostovací aplikace pro otáčení, miniatury, tisk, fullscreen, rozvržení a pomocníky stavů tlačítek. Načtěte tento hostovací soubor po Viewer.ReferenceScripts(...). Při kopírování celé ukázkové implementace udržujte pomocníka a jeho markup <nav id="toolbar"> společně.

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

1. Vygenerujte 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. Vygenerujte skripty pro Viewer a licencované moduly.
4. Načtěte viewerToolbar.js hostovací aplikace.
5. Inicializujte docViewer a uchovejte vzniklý objViewer.
6. Inicializujte každou licencovanou vyhledávací nebo anotační lištu.
7. Zavolejte attach(objViewer) na každé liště.
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 Vieweru. Jeho další hodnota požadavku access a nastavení opakování asynchronního renderování patří k distribuovanému transportu; nemění způsob, jakým jsou Viewer, panel nástrojů nebo lišty sestaveny.

Serverové ochrany jsou důležité: když je volitelná schopnost nedostupná, její skript není vygenerová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>

Obě vložené komponenty generují vlastní DOM lišty. Vyhledávání obsahuje skupiny Find, Options a Results. Anotace obsahuje své nástroje pro tvorbu, ovládání stylů, akce uložení a volitelné exportní/obrázkové akce. Lišty vystavují open(), close(), reset() a isOpen(); vždy po jejich vytvoření jednou zavolejte attach(objViewer).

Ukázka výše vynechává volitelné hostovací callbacky a koncové body exportu/obrázku pro anotace, 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í hostovaného panelu Vieweru.

Otevřít dokument

Na serverové straně je jeden koncový bod: injektovaná služba Viewer otevře dokument a vrátí token relace.

app.MapPost("/api/open", async (Viewer viewer) =>
{
    // Token je neprůhledný — předávejte jej widgetu, nikdy jej nelogujte ani neukládejte.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

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

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

Zavřít dokument

Volání objViewer.Close() proveďte, když uživatel opustí prohlížeč nebo otevře náhradní dokument. V serverově řízených pracovních postupech viewer.CloseDocument(token) okamžitě odstraní uloženou relaci, uvolní vykreslovací engine, smaže jeho bezpečnostní značku a odvolá token. Posuvná expirace nakonec provede stejný úklid, ale pro velké dokumenty se doporučuje explicitní zavření.

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

Zacházejte s tokenem jako s přístupovým oprávněním: nikdy jej nelogujte, nikdy jej neukládejte, předávejte jej pouze widgetu. Identifikuje aktivní relaci dokumentu na serveru a přestane fungovat, když tato relace vyprší — znovu otevřete dokument, 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 vykresluje normálně, ale každá stránka nese vodotisk hodnocení. Viz Nastavení licence pro informace o tom, jak Doconut najde licenci a co se změní, až ji najde.