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.
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á:
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:
<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í:
<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:
@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.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):
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:
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 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 jakoBasePath.- Callbacky jsou možnosti.
onViewerReady,onErrora ostatní patří do objektu předaného dodocViewer(...). Globální funkce pojmenovaná po prohlížeči, jako napříkladctlDoc_ViewerReady, se nikdy nevolá. - Uchovejte prohlížeč a poté 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řipojena |
|---|---|---|
Zdroje Vieweru, připojení a objViewer | Povinné | Jádrový renderér dokumentu |
| Viewer toolbar | Povinné pro kompletní stránku | Značkování hosta; tlačítka volají stejný objViewer |
| Search ribbon | Volitelný, licencovaný modul | doconutSearchBar(...).attach(objViewer) |
| Annotation ribbon | Volitelný, licencovaný modul | doconutAnnotationBar(...).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:
<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:
- 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 vzniklýobjViewer. - Inicializujte každý licencovaný vyhledávací nebo anotační pás.
- Zavolejte
attach(objViewer)na každém pásu. - 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.
<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.
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
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:
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 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á?