Rychlý start

Tento průvodce vezme aplikaci ASP.NET Core z 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í přijít jako první. Volání sezení jsou také vyžadována — výchozí zabezpečení dokumentu Doconut ověřuje každý požadavek stránky vůči stavu sezení ASP.NET. Stav sezení potřebuje mezipaměť: AddDistributedMemoryCache() poskytuje jednu. Aplikace MVC nebo Razor Pages ji již registruje, ale aplikace minimal-API ne, a bez ní se aplikace při spuštění zastaví s Unable to resolve service for type 'IDistributedCache'. Už jste během Instalace 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ž přidávají jednu)
builder.Services.AddSession(); // Zabezpečení dokumentů Doconut je postaveno na ASP.NET session state

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ě nemapuje větev ASP.NET Core. V tomto příkladu host mapuje /doconut, takže klient používá BasePath: 'doconut'. ResourcesPath poskytuje vložený balík 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 stal //doconut/DocImage.axd, což prohlížeč interpretuje jako požadavek na hosta s názvem doconut, a viewer selže s chybou „Obslužný program vieweru nebyl dosažitelný“.

Přidání Vieweru na stránku

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

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

Zacházejte s panelem nástrojů, připojeními modulů a plochou Vieweru jako s jednou stránkovou kompozicí. 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řadí jako Doconut.TestApp a Doconut.TestApp.Distributed:

<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Navigace, zoom, vyhledávání a anotace tlačítka Vieweru -->
</nav>

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

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

Odkazy na prostředky Vieweru

V Razor pohledu injektovaná služba Viewer generuje značky <link> a <script> vieweru v pořadí závislostí — widget je plugin jQuery, 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é 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 vynechávají zdroje volitelného modulu, když aktuální licence tuto schopnost nepovoluje; základní Viewer se stále spustí.

Inicializace prohlížeče

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

let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   'doconut',             // žádný úvodní '/'
    ResPath:    'doconut-res/images',  // žádný úvodní '/'
    onViewerReady: function () {
        // stránky jsou viditelné; zde je bezpečné skrýt indikátor načítání
    },
    // Přeposlat události životního cyklu anotací do vložené pásky, 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);
    }
});

Velikost písmen v možnostech je skutečně smíšená — showThumbs, autoLoad a pageZoom jsou camelCase, ale FitType, BasePath a ResPath jsou PascalCase. Neexistuje žádné konzistentní pravidlo; pokud velikost písmen nesedí, možnost 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 8 instalují následující části společně na jedné stránce:

Ačkoli hlavní panel nástrojů Vieweru je hostové značkování, je instalován spolu s Viewerem a nesmí být nikdy dokumentován jako samostatná kontrola. 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 hostové aplikace pro otáčení, miniatury, tisk, fullscreen, rozvržení a pomocníky stavu tlačítek. Načtěte tento hostový soubor po Viewer.ReferenceScripts(...). Při kopírování celé demo implementace udržujte pomocníka a jeho <nav id="toolbar"> značkování společně.

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

1. Vydat zdroje Vieweru, Search a Annotation společně.
2. Vykreslit panel nástrojů Vieweru, připojení Ribbon a připojení Vieweru společně.
3. Inicializovat docViewer jako první.
4. Vytvořit každý licencovaný Ribbon a připojit jej k tomu samému objViewer.
5. Otevřít dokument a zachovat jeho token pro požadavky modulů.

Doconut.TestApp.Distributed udržuje tuto přesnou UI kompozici a stejný pomocník Viewer‑toolbar. 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 Ribbony sestaveny.

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

Obě vložené komponenty generují vlastní Ribbon DOM. Search obsahuje skupiny Find, Options a Results. Annotation obsahuje své autorovací nástroje, ovládací prvky stylu, akce uložení a volitelné akce exportu/obrázku. Proužky vystavují open(), close(), reset() a isOpen(); vždy zavolejte attach(objViewer) jednou po jejich vytvoření.

Výše uvedený příklad vynechává volitelné hostovské callbacky a koncové body exportu/obrázku pro Annotation, aby byl start co nejmenší. Viz Search a Annotations pro kompletní nastavení specifické pro funkci, nebo Custom Themes pro stylování nebo nahrazení panelu nástrojů Vieweru spravovaného hostem.

Otevřít dokument

Serverová strana má jeden koncový bod: injektovaná služba Viewer otevírá dokument a vrací 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

Zavolejte objViewer.Close(), 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í uzavření.

Dokončený tok požadavku 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 neukládejte do logů, nikdy jej neukládejte trvale, 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 na wwwroot/files/Sample.pdf, spusťte dotnet run a otevřete stránku, která hostí widget. První stránka se vykreslí v prohlížeči s panelem miniatur na levé straně. 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 vodoznak hodnocení. Viz Nastavení licence pro informace o tom, jak Doconut najde licenci a co se změní, až ji najde.