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: registrace serveru, kompletní balíček Prohlížeče (panel nástrojů Prohlížeče, připojení Prohlížeče a volitelné pásky Vyhledávání/Anotace), odkazy na zdroje, inicializace klienta, otevření dokumentu a spuštění.

Nastavení serveru

AddDoconut() registruje služby; UseDoconutResources() a UseDoconut() propojují middleware. Volání zdrojů musí přijít jako 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 na stránku oproti stavu relace ASP.NET. Stav relace 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.

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

app.UseSession();          // volat 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 namapujte middleware dokumentu na explicitní větev a udržujte čtyři nastavení cesty zarovnaná:

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ík na /doconut-res, a cesta k obrázkovému zdroji widgetu je tedy ResPath: 'doconut-res/images'. Zapište obojí bez úvodní lomítka: Prohlížeč si přidá vlastní, takže '/doconut' by se stal //doconut/DocImage.axd, což prohlížeč interpretuje jako požadavek na hostitele s názvem doconut, a Prohlížeč selže s chybou "Obsluha prohlížeče nebyla dosažitelná".

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

Prohlížeč 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>

Považujte panel nástrojů, připojení modulů a plochu Prohlížeče 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 Prohlížeči 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>

Odkazování na zdroje prohlížeče

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

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 Prohlížeče požádejte o zdroje Prohlížeče a 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 pásky Vyhledávání nebo Anotace bez nich, připojení Prohlížeče a instance docViewer. ReferenceCss a ReferenceScripts vynechají zdroje volitelného modulu, pokud aktuální licence tuto funkci nepovoluje; základní Prohlížeč se stále spustí.

Inicializace prohlížeče

Klientský widget je plugin jQuery. 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é; je bezpečné zde 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).

Čtyři další 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 umístěny o jednu složku pod kořenem zdrojů. S 'doconut-res' vrací každá ikona 404: žádné glyphy 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 například ctlDoc_ViewerReady, se nikdy nevolá.
  • Uchovejte prohlížeč a poté 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řipojena
Zdroje Vieweru, připojení a objViewerPovinnéJádrový renderér dokumentu
Viewer toolbarPovinné pro kompletní stránkuZnačkování hosta; tlačítka volají stejný objViewer
Search ribbonVolitelný, licencovaný moduldoconutSearchBar(...).attach(objViewer)
Annotation ribbonVolitelný, licencovaný moduldoconutAnnotationBar(...).attach(objViewer)

Ačkoli hlavní panel nástrojů Vieweru je značkování hosta, 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, celou obrazovku, 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 vzniklý objViewer.
  6. Inicializujte každý licencovaný vyhledávací nebo anotační pás.
  7. Zavolejte attach(objViewer) na každém pásu.
  8. Otevřete dokument a zachovejte 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í funkce jQuery pluginu 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í svůj vlastní DOM pásu. Vyhledávání obsahuje skupiny Najít, Možnosti a Výsledky. Anotace obsahuje své nástroje pro tvorbu, ovládací prvky 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í.

Výše uvedený příklad vynechává volitelné hostitelské callbacky a koncové body exportu/obrázku anotací, 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 vlastněného hostitelem.

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

Zavolejte objViewer.Close(true), 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žadavku 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 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

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.

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