Rychlý start

Vykreslete svůj první dokument během několika minut

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 Viewer (panel nástrojů Viewer, připojení Viewer a volitelné pásy Search/Annotation), odkazy na prostředky, inicializaci klienta, otevření dokumentu a spuštění.

Nastavení serveru

AddDoconut() registruje služby; UseDoconutResources() a UseDoconut() propojují middleware. Volání zdrojů musí být první. UseDoconut() odpovídá na každý požadavek, který k němu dorazí, takže jej připojte na vlastní větev pomocí app.Map. Volání relace jsou také vyžadována — výchozí zabezpečení dokumentu Doconut ověřuje každý požadavek stránky vůči stavu relace ASP.NET. Stav relace potřebuje mezipaměť: AddDistributedMemoryCache() poskytuje jednu. Aplikace MVC nebo Razor Pages ji již registruje, ale minimal-API aplikace ne, a bez ní se aplikace zastaví při spuštění s Unable to resolve service for type 'IDistributedCache'. Už jste během Instalace zaregistrovali Doconut? Přeskočte na další sekci.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // session state potřebuje mezipaměť (MVC/Razor Pages již přidávají jednu)
builder.Services.AddSession(); // Bezpečnost dokumentu Doconut je založena na ASP.NET session state

app.UseSession();          // volání UseSession() před UseDoconut()
app.UseDoconutResources(); // musí být zaregistrováno před UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

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

csharp
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íček na /doconut-res, a cesta k obrázkovému prostředku widgetu je tedy ResPath: 'doconut-res/images'. Zapište oba 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 "The viewer handler could not be reached".

Přidejte viewer na stránku

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

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

Zacházejte s panelem nástrojů, připojeními modulů a plochou Viewer jako s jednou stránkovou kompozicí. Search a Annotation vkládají své vložené pásy do volitelných připojení, ale tyto moduly nejsou nikdy samostatné: vždy se připojují k Viewer na stejné stránce. Použijte toto pořadí:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer navigace, zoom, Search a Annotation tlačítka -->
</nav>

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

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

Odkaz na prostředky vieweru

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

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

Pro kompletní balíček Viewer požádejte o Viewer a prostředky modulů najednou:

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 a IncludeViewerScripts jsou povinné základní příznaky. Nikdy nepublikujte příklad Search nebo Annotation Ribbon bez nich, připojení Viewer a instance docViewer instance. ReferenceCss a ReferenceScripts vynechávají prostředky volitelného modulu, když aktuální licence tuto funkci 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ód):

javascript
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).

Další čtyři podrobnosti selžou bez chybové zprávy:

  • BasePath nemá úvodní lomítko. 'doconut' požaduje /doconut/DocImage.axd; '/doconut' vytváří //doconut/DocImage.axd, který prohlížeč interpretuje jako požadavek na jiný hostitel.
  • ResPath: 'doconut-res/images' — ikony jsou o jednu složku pod kořenem zdrojů. S 'doconut-res' každá ikona vrací 404: žádné glykfy na panelu nástrojů a žádný načítací spinner, zatímco samotný dokument se stále vykresluje. Úvodní lomítko to rozbije stejným způsobem jako BasePath.
  • Callbacky jsou možnosti. onViewerReady, onError a ostatní patří do objektu předaného do docViewer(...). Globální funkce pojmenovaná po prohlížeči, jako je ctlDoc_ViewerReady, se nikdy nevolá.
  • Udržujte prohlížeč, pak zavolejte View samostatně. docViewer(...) vrací objekt s Zoom, Next a FitType; View(...) vrací něco jiného. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) vykreslí dokument, pak selže s objViewer.Zoom is not a function při prvním kliknutí na panel nástrojů.

Sestavení kompletního balíčku Vieweru

Kompletní stránka prohlížeče nainstaluje následující části společně:

Část balíčkuPožadavekJak je připojeno
Zdroje Vieweru, připojení a objViewerVyžadovánoJádrový renderér dokumentu
Panel nástrojů VieweruVyžadováno pro kompletní stránkuZnačkování hostitele; tlačítka volají stejný objViewer
Vyhledávací pásVolitelný, licencovaný moduldoconutSearchBar(...).attach(objViewer)
Anotační pásVolitelný, licencovaný moduldoconutAnnotationBar(...).attach(objViewer)

Ačkoli hlavní panel nástrojů Vieweru je host markup, je instalován spolu s Viewerem a nikdy by neměl být dokumentován jako izolovaná 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:

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>

Pomocníci pro rotaci, miniatury, tisk, fullscreen, rozvržení a stav tlačítek patří do vašeho vlastního skriptu panelu nástrojů, který volá stejný objViewer. Načtěte jej po Viewer.ReferenceScripts(...) a udržujte jej spolu s jeho <nav id="toolbar"> značkováním.

Udržujte toto pořadí inicializace:

  1. Vygenerujte CSS pro Viewer a licencované moduly.
  2. Vykreslete panel nástrojů Vieweru, připojení vyhledávání/anotace a připojení Vieweru společně.
  3. Vygenerujte skripty pro Viewer a licencované moduly.
  4. Načtěte vlastní skript pomocníka panelu nástrojů hostitelské aplikace.
  5. Inicializujte docViewer a uchovejte výsledný objViewer.
  6. Inicializujte každý licencovaný vyhledávací nebo anotační pás.
  7. Zavolejte attach(objViewer) na každý pás.
  8. Otevřete dokument a uchovejte jeho token pro požadavky Vieweru a modulů.

V distribuovaném nasazení patří dodatečná hodnota požadavku access a nastavení opakování asynchronního renderování k transportu; nemění to 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í vygenerován, takže její jQuery plug-in funkce neexistuje.

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>

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

Příklad výše vynechává volitelné hostitelské callbacky a koncové body exportu/obrázku pro Anotaci, 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í hostitelem vlastněného panelu nástrojů Vieweru.

Otevřít dokument

Serverová strana má jeden koncový bod: injektovaná služba Viewer otevírá dokument a vrací token relace.

csharp
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):

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

Zavřít dokument

Volání objViewer.Close(true) proveďte, když uživatel opustí prohlížeč nebo otevře náhradní dokument: vyčistí widget a odešle požadavek na uzavření na server. objViewer.Close() bez argumentu vyčistí pouze widget. 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 explicitní uzavření se doporučuje u velkých dokumentů.

Dokončený tok požadavků je:

text
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 nosičovým oprávněním: nikdy jej nezaznamenávejte, 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 a získáte nový.

Spustit

Umístěte PDF na 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 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.

Byla tato stránka užitečná?