Rychlý start
Vykreslete svůj první dokument během několika minut
Tento průvodce vezme ASP.NET Core aplikaci 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ásky Vyhledávání/Anotace), odkazy na zdroje, inicializaci klienta, otevření dokumentu a spuštění.
Hostitelská aplikace musí cílit na runtime, který podporuje netstandard2.1 — .NET Core 3.0 nebo novější.
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 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 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 již přidávají)
builder.Services.AddSession(); // Zabezpečení dokumentu Doconut 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());Toto nastavení zachovává historický tvar požadavku DocImage.axd a připojuje middleware dokumentu na odpovídající větev. Toto je uspořádání, které je třeba zkopírovat, když posouváte existující .NET Standard aplikaci dál, protože klient nadále volá stejnou URL, kterou vždy používal:
builder.Services.AddDoconut(options =>
{
options.UnsafeMode = false; // ponechat kontrolu relace Doconut povolenou
options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // stav relace potřebuje mezipaměť (MVC/Razor Pages ji již přidávají)
builder.Services.AddSession(options =>
{
options.IdleTimeout = TimeSpan.FromSeconds(3600);
options.Cookie.HttpOnly = true;
options.Cookie.IsEssential = true;
});
// Vyžadováno pro vícebytové kódování v některých formátech dokumentů.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources(); // PŘED větví dokumentu
app.MapWhen(
context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconut() nepřijímá žádné možnosti v tomto vydání — vše bylo přesunuto do AddDoconut().
MiddlewarePath je koordinační hodnota; sama o sobě nemapuje větev ASP.NET Core.
S výše uvedenou větví DocImage.axd klient používá BasePath: '/'; s app.Map("/doconut", ...) z minimálního nastavení používá BasePath: 'doconut'.
ResourcesPath poskytuje vložený balíček na /doconut-res a cesta k obrázkovému zdroji widgetu je tedy ResPath: 'doconut-res/images'.
Přidání vieweru na stránku
Viewer je požadovaným jádrem stránky. Jeho vykreslovací plocha používá dva vnořené divs:
<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í. 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.
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Tlačítka prohlížeče: navigace, zoom, hledání a anotace -->
</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 pohledu injektovaná služba Viewer vydává 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:
@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 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
Search nebo Annotation Ribbon příklad bez nich, montáž Vieweru a docViewer
instanci. ReferenceCss a ReferenceScripts vynechávají zdroje volitelného modulu, když
aktuální licence tuto schopnost nepovoluje; základní Viewer se stále spustí.
Tyto volání nahrazují ručně kopírované soubory skriptů. Pokud aplikace stále načítá své vlastní
docViewer.js, documentLinks.js nebo docViewer.UI.js, odstraňte tyto značky, jakmile stránka
funguje s vydanými zdroji — viz průvodce migrací.
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: '/', // větev DocImage.axd; 'doconut' s app.Map("/doconut", ...)
ResPath: 'doconut-res/images',
onViewerReady: function () {
// stránky jsou viditelné; je bezpečné skrýt zde indikátor načítání
},
// Přeposílat 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);
}
});Čtyři detaily rozhodují, zda tato stránka vůbec funguje:
- Callbacky jsou možnosti.
onViewerReady,onViewerBusy,onCopyaonAutoLoadStatusjsou předány v objektu možností. Předchozí viewer odvozoval názvy globálních funkcí z id kontejneru a volal je; tento ne. Handler deklarovaný pouze jako globální funkce se nikdy nespustí a nic není hlášeno. ResPathukazuje na předponu zdrojů, nikoli na kořen aplikace. S výchozímResourcesPath, tato hodnota jedoconut-res/images. Pokud jste změniliResourcesPath, použijte vlastní předponu. Ikony jsou umístěny o jednu složku pod kořenem zdrojů: s'doconut-res', každá ikona vrací 404, zatímco dokument se stále vykresluje.BasePathnemá úvodní lomítko kromě hodnoty kořene stránky'/'.'doconut'požaduje/doconut/DocImage.axd;'/doconut'vytváří//doconut/DocImage.axd, který prohlížeč interpretuje jako požadavek na jiný hostitel.- Nechte viewer, pak zavolejte
Viewsamostatně.docViewer(...)vrací objekt sZoom,NextaFitType;View(...)vrací něco jiného.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)vykreslí dokument, pak selže sobjViewer.Zoom is not a functionpři prvním kliknutí na panel nástrojů.
Všechny tyto selhávají tiše — viz Řešení problémů a průvodce migrací.
Velikost písmen v možnostech je skutečně smíšená — showThumbs, autoLoad a pageZoom jsou ve stylu camelCase, ale FitType, BasePath a ResPath jsou ve stylu PascalCase. Neexistuje žádné konzistentní pravidlo; pokud velikost písmen použijete špatně, možnost je tiše ignorována (widget se vrátí k výchozímu nastavení místo vyhození chyby).
Sestavte kompletní balíček Vieweru
Kompletní stránka Vieweru nainstaluje následující části dohromady:
| Část balíčku | Požadavek | Jak je připojeno |
|---|---|---|
Zdroje Vieweru, připojení a objViewer | Povinné | Jádrový vykreslovač dokumentu |
| Panel nástrojů Vieweru | Povinné pro kompletní stránku | Hostovací značkování; tlačítka volají stejný objViewer |
| Panel vyhledávání | Volitelný, licencovaný modul | doconutSearchBar(...).attach(objViewer) |
| Panel anotací | Volitelný, licencovaný modul | doconutAnnotationBar(...).attach(objViewer) |
Ačkoliv je hlavní panel nástrojů Vieweru hostovací značkování, je instalován vedle Vieweru a nikdy by neměl být dokumentován jako samostatná komponenta. 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>Dodržujte následující pořadí inicializace:
- Vygenerujte CSS pro Viewer a licencované moduly.
- Vykreslete panel nástrojů Vieweru, připojení vyhledávání/anotací a připojení Vieweru společně.
- Vygenerujte skripty pro Viewer a licencované moduly.
- Načtěte pomocný skript panelu nástrojů hostitelské aplikace.
- Inicializujte
docViewera uchovejte výslednýobjViewer. - Inicializujte každý licencovaný panel vyhledávání nebo anotací.
- Zavolejte
attach(objViewer)na každém panelu. - Otevřete dokument a uchovejte jeho token pro požadavky Vieweru a modulů.
Serverové ochrany jsou důležité: když je volitelná funkce nedostupná, její skript není vygenerován, takže její jQuery plug‑in funkce neexistuje.
<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>Obě vložené komponenty generují svůj vlastní DOM panelu. 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. Panely vystavují open(), close(), reset() a isOpen(); vždy po jejich vytvoření jednou zavolejte attach(objViewer).
Výše uvedený příklad vynechává volitelné hostitelské zpětné volání a koncové body exportu/obrázku pro anotace, 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. Otevírání je v tomto vydání asynchronní.
app.MapPost("/api/open", async (Viewer viewer) =>
{
// Token je neprůhledný — předávejte jej widgetu, nikdy jej neukládejte do logu ani neperzistujte ho.
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 => {
token = data.token;
objViewer.View(token);
});Před prvním otevřením není nic, co by se mělo připravovat. Pokud přenášíte aplikaci dál, odstraňte jakékoli volání InitCache() a příslušný příznak — metoda již neexistuje.
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 zavř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í zavření se doporučuje u velkých dokumentů.
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 / CloseDocumentZacházejte s tokenem jako s přístupovým oprávněním: nikdy jej nezaznamenávejte, nikdy neukládejte, předávejte jej pouze widgetu. Identifikuje aktivní relaci dokumentu na serveru a přestane fungovat, když relace vyprší — dokument znovu otevřete, 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 vodotisk s hodnocením. 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á?