Avvio Rapido
Renderizza il tuo primo documento in pochi minuti
Questa guida porta un'app ASP.NET Core da un Program.cs vuoto a un documento renderizzato nel browser: registrazione del server, il pacchetto completo Viewer (barra degli strumenti Viewer, montaggio Viewer e nastri opzionali di Ricerca/Annotazione), riferimenti alle risorse, inizializzazione del client, apertura del documento e esecuzione.
Configurazione del server
AddDoconut() registra i servizi; UseDoconutResources() e UseDoconut() collegano il middleware. La chiamata alle risorse deve venire per prima. UseDoconut() risponde a ogni richiesta che le arriva, quindi montala su un ramo proprio con app.Map. Le chiamate di sessione sono necessarie anche — la sicurezza predefinita dei documenti di Doconut convalida ogni richiesta di pagina contro lo stato della sessione ASP.NET. Lo stato della sessione richiede una cache: AddDistributedMemoryCache() ne fornisce una. Un'app MVC o Razor Pages la registra già, ma un'app minimal-API no, e senza di essa l'app si arresta all'avvio con Unable to resolve service for type 'IDistributedCache'. Hai già registrato Doconut durante Installazione? Salta alla sezione successiva.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // lo stato della sessione richiede una cache (MVC/Razor Pages ne aggiunge già una)
builder.Services.AddSession(); // La sicurezza dei documenti Doconut si basa sullo stato della sessione ASP.NET
app.UseSession(); // chiama UseSession() prima di UseDoconut()
app.UseDoconutResources(); // deve essere registrato prima di UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());Per una struttura dei percorsi in stile produzione, mappa il middleware dei documenti su un ramo esplicito e mantieni allineate le quattro impostazioni di percorso:
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 è un valore di coordinazione; non mappa un ramo ASP.NET Core da solo. In questo esempio l'host mappa /doconut, quindi il client utilizza BasePath: 'doconut'. ResourcesPath serve il bundle incorporato su /doconut-res, e il percorso della risorsa immagine del widget è quindi ResPath: 'doconut-res/images'. Scrivi entrambi senza una barra iniziale: il visualizzatore ne aggiunge una automaticamente, quindi '/doconut' diventerebbe //doconut/DocImage.axd, che il browser interpreta come una richiesta a un host chiamato doconut, e il visualizzatore fallisce con "Il gestore del visualizzatore non è stato raggiunto".
Aggiungi il visualizzatore a una pagina
Il Viewer è il nucleo richiesto della pagina. La sua superficie di rendering utilizza due div nidificati:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Tratta la barra degli strumenti, i montaggi dei moduli e la superficie del Viewer come una singola composizione di pagina. Ricerca e Annotazione iniettano i loro nastri incorporati nei montaggi opzionali, ma questi moduli non sono mai autonomi: si collegano sempre al Viewer nella stessa pagina. Usa quest'ordine:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Pulsanti di navigazione, zoom, ricerca e annotazione del visualizzatore -->
</nav>
<div id="searchBarMount"></div>
<div id="annBarMount"></div>
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Riferisci le risorse del visualizzatore
In una vista Razor, il servizio Viewer iniettato emette i tag <link> e <script> del visualizzatore in ordine di dipendenza — il widget è un plugin jQuery, quindi jQuery deve essere caricato prima degli script del visualizzatore:
@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
}))Per il pacchetto completo Viewer, richiedi insieme le risorse del Viewer e dei moduli:
@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 e IncludeViewerScripts sono le flag di base obbligatorie. Non pubblicare mai un
esempio di Nastro di Ricerca o Annotazione senza di esse, il montaggio del Viewer e un'istanza docViewer.
ReferenceCss e ReferenceScripts omettono le risorse di un modulo opzionale quando
la licenza corrente non concede tale capacità; il Viewer di base si avvia comunque.
Inizializza il visualizzatore
Il widget lato client è un plugin jQuery. Questo è un set minimo di opzioni di inizializzazione reali (non pseudocodice):
let searchBar = null;
let annBar = null;
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: 'doconut', // nessun '/' iniziale
ResPath: 'doconut-res/images', // nessun '/' iniziale
onViewerReady: function () {
// le pagine sono visibili; è sicuro nascondere qui un indicatore di caricamento
},
// Inoltra gli eventi del ciclo di vita delle annotazioni al nastro incorporato quando è presente.
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});La capitalizzazione delle opzioni è davvero mista — showThumbs, autoLoad e pageZoom sono in camelCase, ma FitType, BasePath e ResPath sono in PascalCase. Non esiste una regola coerente; se la capitalizzazione è errata l'opzione viene silenziosamente ignorata (il widget ripiega sul valore predefinito invece di generare un errore).
Altri quattro dettagli falliscono senza un messaggio di errore:
BasePathnon ha lo slash iniziale.'doconut'richiede/doconut/DocImage.axd;'/doconut'produce//doconut/DocImage.axd, che il browser interpreta come una richiesta a un altro host.ResPath: 'doconut-res/images'— le icone si trovano una cartella sotto la radice delle risorse. Con'doconut-res', ogni icona restituisce 404: nessuna icona della barra degli strumenti e nessuno spinner di caricamento, mentre il documento stesso viene comunque renderizzato. Uno slash iniziale lo rompe allo stesso modo diBasePath.- I callback sono opzioni.
onViewerReady,onErrore gli altri vanno nell'oggetto passato adocViewer(...). Una funzione globale chiamata come il visualizzatore, ad esempioctlDoc_ViewerReady, non viene mai chiamata. - Mantieni il visualizzatore, poi chiama
Viewseparatamente.docViewer(...)restituisce l'oggetto conZoom,NexteFitType;View(...)restituisce qualcos'altro.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)renderizza il documento, poi fallisce conobjViewer.Zoom is not a functional primo click sulla barra degli strumenti.
Assembla il pacchetto completo del Visualizzatore
Una pagina completa del visualizzatore installa le seguenti parti insieme:
| Parte del pacchetto | Requisito | Come è collegata |
|---|---|---|
Risorse del visualizzatore, mount e objViewer | Obbligatorio | Renderer di documento core |
| Barra degli strumenti del visualizzatore | Obbligatorio per una pagina completa | Markup host; i pulsanti chiamano lo stesso objViewer |
| Barra di ricerca | Opzionale, modulo con licenza | doconutSearchBar(...).attach(objViewer) |
| Barra di annotazione | Opzionale, modulo con licenza | doconutAnnotationBar(...).attach(objViewer) |
Sebbene la barra degli strumenti principale del Visualizzatore sia markup host, è installata accanto al Visualizzatore e non deve mai essere documentata come un controllo isolato. Questo mantiene il suo layout, le etichette, le icone e le regole di autorizzazione sotto il controllo della tua applicazione mentre ogni pulsante controlla la stessa istanza del Visualizzatore:
<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>Gli helper per rotazione, miniatura, stampa, schermo intero, layout e stato dei pulsanti appartengono al tuo script della barra degli strumenti, che chiama lo stesso objViewer. Caricalo dopo Viewer.ReferenceScripts(...) e tienilo insieme al suo markup <nav id="toolbar">.
Mantieni questo ordine di inizializzazione:
- Emessi CSS per il Visualizzatore e i moduli con licenza.
- Renderizza la barra degli strumenti del Visualizzatore, i mount di Ricerca/Annotazione e il mount del Visualizzatore insieme.
- Emessi script per il Visualizzatore e i moduli con licenza.
- Carica lo script helper della barra degli strumenti dell'applicazione host.
- Inizializza
docViewere conserva ilobjViewerrisultante. - Inizializza ogni barra di Ricerca o Annotazione con licenza.
- Chiama
attach(objViewer)su ogni barra. - Apri il documento e conserva il suo token per le richieste del Visualizzatore e dei moduli.
In un deployment distribuito, il valore di richiesta aggiuntivo access e le impostazioni di retry del rendering asincrono appartengono al trasporto; non modificano il modo in cui il Visualizzatore, la barra degli strumenti o le barre sono assemblate.
Le protezioni lato server sono importanti: quando una funzionalità opzionale non è disponibile, il suo script non viene emesso, quindi la sua funzione plugin jQuery non esiste.
<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>Entrambi i componenti incorporati generano il proprio DOM della barra. La ricerca contiene i gruppi Trova, Opzioni e Risultati. L'annotazione contiene i suoi strumenti di authoring, i controlli di stile, le azioni di salvataggio e le azioni opzionali di esportazione/immagine. Le barre espongono open(), close(), reset() e isOpen(); chiama sempre attach(objViewer) una volta dopo averle create.
L'esempio sopra omette i callback opzionali dell'host e gli endpoint di esportazione/immagine dell'Annotazione per mantenere l'avvio minimale. Vedi Ricerca e Annotazioni per la configurazione completa specifica delle funzionalità, o Temi personalizzati per stilizzare o sostituire la barra degli strumenti del Visualizzatore di proprietà dell'host.
Apri un documento
Il lato server è un unico endpoint: il servizio Viewer iniettato apre il documento e restituisce un token di sessione.
app.MapPost("/api/open", async (Viewer viewer) =>
{
// Il token è opaco — passalo al widget, non registrarlo né conservarlo.
string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});Il client recupera quel token e lo passa al widget con objViewer.View(token):
fetch('/api/open', { method: 'POST' })
.then(resp => resp.json())
.then(data => {
token = data.token;
objViewer.View(token);
});Chiudi il documento
Chiama objViewer.Close(true) quando l'utente lascia il visualizzatore o apre un documento di sostituzione: pulisce il widget e invia una richiesta di chiusura al server. objViewer.Close() senza argomento pulisce solo il widget. Nei flussi di lavoro guidati dal server, viewer.CloseDocument(token) rimuove immediatamente la sessione nella cache, elimina il motore di rendering, cancella il suo marcatore di sicurezza e revoca il token. L'espirazione scorrevole alla fine esegue la stessa pulizia, ma è consigliata una chiusura esplicita per documenti di grandi dimensioni.
Il flusso di richiesta completato è:
AddDoconut + middleware
-> render CSS/scripts and mount div
-> initialize docViewer
-> OpenDocumentAsync
-> return opaque token
-> objViewer.View(token)
-> page/search/annotation requests
-> Close / CloseDocumentTratta il token come una credenziale di tipo bearer: non registrarlo mai, non conservarlo mai, consegnalo solo al widget. Identifica una sessione di documento attiva sul server e smette di funzionare quando quella sessione scade — riapri il documento per ottenerne uno nuovo.
Eseguilo
Posiziona un PDF in wwwroot/files/Sample.pdf, esegui dotnet run e apri la pagina che ospita il widget. La prima pagina viene renderizzata nel visualizzatore, con un pannello di miniature a sinistra. Se non accade, consulta Risoluzione dei problemi.
Cosa ottieni senza licenza
Una licenza mancante non genera errori. Il visualizzatore rende normalmente, ma ogni pagina porta una filigrana di valutazione. Vedi Configurazione della licenza per capire come Doconut trova una licenza e cosa cambia una volta trovata.
Questa pagina è stata utile?