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.
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:
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:
<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í:
<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:
@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.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):
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:
BasePathnemá ú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 jakoBasePath.- Callbacky jsou možnosti.
onViewerReady,onErrora ostatní patří do objektu předaného dodocViewer(...). Globální funkce pojmenovaná po prohlížeči, jako jectlDoc_ViewerReady, se nikdy nevolá. - Udržujte prohlížeč, 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ů.
Sestavení kompletního balíčku Vieweru
Kompletní stránka prohlížeče nainstaluje následující části společně:
| Část balíčku | Požadavek | Jak je připojeno |
|---|---|---|
Zdroje Vieweru, připojení a objViewer | Vyžadováno | Jádrový renderér dokumentu |
| Panel nástrojů Vieweru | Vyžadováno pro kompletní stránku | Značkování hostitele; tlačítka volají stejný objViewer |
| Vyhledávací pás | Volitelný, licencovaný modul | doconutSearchBar(...).attach(objViewer) |
| Anotační pás | Volitelný, licencovaný modul | doconutAnnotationBar(...).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:
<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:
- Vygenerujte CSS pro Viewer a licencované moduly.
- Vykreslete panel nástrojů Vieweru, připojení vyhledávání/anotace a připojení Vieweru společně.
- Vygenerujte skripty pro Viewer a licencované moduly.
- Načtěte vlastní skript pomocníka panelu nástrojů hostitelské aplikace.
- Inicializujte
docViewera uchovejte výslednýobjViewer. - Inicializujte každý licencovaný vyhledávací nebo anotační pás.
- Zavolejte
attach(objViewer)na každý pás. - 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.
<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.
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 => {
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:
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 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á?