Visualizzatore
La classe principale del visualizzatore di documenti
Viewer (namespace Doconut) è il punto di ingresso pubblico per aprire documenti da pagine Razor, controller MVC, componenti Blazor o API minime. È sealed, registrato come servizio transient da AddDoconut(), e risolto tramite iniezione del costruttore — non costruirlo direttamente.
Viewer non mantiene alcuno stato per richiesta e intenzionalmente non implementa IDisposable: le sessioni dei documenti vivono indipendentemente nella cache di sessione, quindi la disposizione del servizio non potrebbe mai chiudere un documento aperto (vedi Concetti di base → Come funziona il visualizzatore).
ApriDocumentoAsync
Apre un documento e restituisce il token di sessione che il widget client utilizza per tutte le richieste successive.
| Sovraccarico | Quando utilizzare |
|---|---|
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default) | Apertura da disco con rilevamento automatico del formato e configurazione predefinita del formato |
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default) | Sono necessarie opzioni di rendering per formato (PdfConfig, WordConfig, …) |
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default) | Il documento non è un file su disco (upload, database, blob). fileInfo deve contenere l'estensione corretta — essa guida il rilevamento del formato |
// Apertura semplice
string token = await viewer.OpenDocumentAsync(path);
// Con configurazione e opzioni per formato
token = await viewer.OpenDocumentAsync(
path,
new PdfConfig { AllowSearch = true, AllowCopy = true },
new DocOptions { TimeOut = 30 });
// Da un caricamento
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));Eccezioni da gestire:
LicenseException— una licenza trovata viene rifiutata (il messaggio contiene il motivo del rifiuto), o il formato richiede una capacità di plugin che non è più concessa. La scadenza del calendario senza un messaggio di rifiuto degrada a rendering con filigrana invece di lanciare un'eccezione.FormatNotSupportedException—Document format '<extension>' is not supported.InvalidDataException— il contenuto del file è corrotto o non corrisponde alla sua estensione.
ChiudiDocumento
void CloseDocument(string token)Rimuove la sessione dalla cache (disponendo immediatamente il motore del documento), elimina il marcatore di sicurezza e revoca il permesso di accesso. Facoltativo — la scadenza scorrevole esegue la stessa pulizia — ma è consigliata per documenti di grandi dimensioni.
OttieniConteggioPagine
int GetPageCount(string token)Numero totale di pagine della sessione aperta. Lancia InvalidOperationException (Document session not found. Please re-open document.) se il token è sconosciuto o scaduto, e ArgumentException per un token vuoto.
OttieniDimensioniPagina
(int Width, int Height) GetPageDimensions(string token, int page = 1)La dimensione predefinita della pagina renderizzata del documento al 100 % di zoom — lo spazio di coordinate per le annotazioni costruite nel codice. page è accettato per compatibilità; il risultato è il valore predefinito del documento. Lancia InvalidOperationException (Document session not found. Please re-open document.) se il token è sconosciuto o scaduto, e ArgumentException per un token vuoto.
OttieniNomiFogliDiLavoro
IReadOnlyList<string> GetWorksheetNames(string token)Restituisce i nomi dei fogli di lavoro di un foglio di calcolo aperto, nell'ordine del workbook, o una lista vuota quando il documento aperto non è un foglio di calcolo.
Vengono elencati solo i fogli di lavoro renderizzati: i fogli nascosti e vuoti sono esclusi, e quando ExcelConfig.SheetNames limita il rendering, appaiono solo quei fogli. Un foglio di lavoro non è sempre una pagina — uno molto grande viene renderizzato su più pagine. Lancia InvalidOperationException (Document session not found. Please re-open document.) se il token è sconosciuto o scaduto, e ArgumentException per un token vuoto.
Aggiunto nella 26.9.0.
Flag di capacità
| Membro | Significato |
|---|---|
bool IsSearchEnabled | La licenza corrente concede Search |
bool IsAnnotationEnabled | La licenza corrente concede Annotation |
Usa questi in una vista Razor per renderizzare un Ribbon con licenza solo quando il server lo fornirà effettivamente — vedi Guida rapida.
DocOptions
Opzioni per apertura, indipendenti dal formato (namespace Doconut):
| Tipo | Proprietà | Predefinito | Descrizione |
|---|---|---|---|
string | Password | "" | Password per documenti protetti (copiata automaticamente nella configurazione del formato). |
int | ImageResolution | 0 | Obsoleto. Conservato solo per compatibilità — impostare ImageResolution nella configurazione del formato invece. |
string | Watermark | "" | Testo personalizzato della filigrana disegnato sulle pagine renderizzate. Stringa di formato: "^Text~Color~FontSize~FontName~Opacity~Angle", ad es. "^Sample Copy~Red~24~Verdana~80~-45". |
int | TimeOut | 60 | Scadenza scorrevole della sessione in minuti. |
bool | IsSecured | true | Non attualmente applicato — riservato. Il binding del token è controllato globalmente da DoconutOptions.UnsafeMode (vedi Concetti di base → Sessioni e sicurezza). |
La classe espone anche proprietà specializzate che sono intenzionalmente al di fuori del normale flusso di visualizzazione a singolo host:
| Tipo | Proprietà | Predefinito | Descrizione |
|---|---|---|---|
bool | IsWebFarm | false | Obsoleto — non ha effetto. Pubblica il documento con DistributedDocumentPublisher.PublishAsync (o IDistributedPublishQueue.EnqueueAsync) e imposta FileShareConfig.RootPath invece. |
string | WebFarmPath | "" | Obsoleto — non ha effetto. Usa FileShareConfig.RootPath invece. |
bool | EditMode | false | Riservato per il flusso di lavoro dell'Editor distribuito separatamente; lascia false per il visualizzatore standard. |
Filigrana personalizzata
DocOptions.Watermark utilizza sei campi separati da tilde. Un ^ opzionale iniziale richiede il layout a tutti gli angoli:
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Campo | Esempio | Significato |
|---|---|---|
Prefisso ^ | ^ | Layout opzionale a tutti gli angoli. Senza di esso, viene usato il posizionamento normale della filigrana. |
| Testo | Confidential | Testo renderizzato su ogni pagina. Non deve essere vuoto. |
| Colore | Red | Colore nominato compreso dal livello di disegno. |
| DimensioneFont | 24 | Dimensione del carattere; input numerico non valido ricade sul valore predefinito del renderer. |
| NomeFont | Verdana | Famiglia di caratteri richiesta. Assicurati che sia installata nell'ambiente di distribuzione. |
| Opacità | 80 | Valore byte da 0 a 255. Deve essere analizzato correttamente. |
| Angolo | -45 | Angolo di rotazione in gradi; input numerico non valido ricade sul valore predefinito. |
Il parser si aspetta esattamente sei campi dopo il ^ opzionale. Una definizione non valida viene sostituita dal fallback visibile Invalid Watermark dell'SDK invece di scomparire silenziosamente.
Decisione di licenza
| Stato della licenza | Valore personalizzato fornito | Risultato renderizzato |
|---|---|---|
| Licenza viewer a pagamento valida | No | Pagina pulita |
| Licenza viewer a pagamento valida | Sì | Filigrana personalizzata |
| Viewer base Temporaneo/Demo attivo | No | Pagina del viewer base pulita |
| Viewer base Temporaneo/Demo attivo | Sì | Filigrana personalizzata quando si applica il percorso del viewer base pulito |
| Licenza mancante, rifiutata, scaduta, versione errata o dominio non valido | Qualsiasi | Filigrana di applicazione/valutazione; il valore personalizzato non la sovrascrive |
| Rendering del plugin secondo le regole di valutazione | Qualsiasi | Filigrana di valutazione |
La stessa decisione viene applicata alle immagini delle pagine servite e alle esportazioni delle annotazioni. L'output GIF animato è marchiato fotogramma per fotogramma. Una filigrana personalizzata è quindi una funzionalità dell'applicazione con licenza, non un modo per sostituire o sopprimere la filigrana di valutazione.
API delle Annotazioni
Caricamento e esportazione delle annotazioni lato server. La guida completa si trova in Guide → Annotazioni; l'interfaccia è:
| Membro | Scopo |
|---|---|
AnnotationManager GetAnnotationManager(string token) | Manager legato alle dimensioni della pagina della sessione aperta |
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight) | Manager con dimensioni della pagina esplicite |
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight) | Manager indipendente dalla sessione |
void LoadAnnotationData(string token, AnnotationManager manager) | Carica le annotazioni create in C# nella sessione |
void LoadAnnotationData(string token, string annotationData) | Carica le annotazioni dalla pagina codificata/Base64 involucro restituito da AnnotationManager.GetAnnotationData() |
void LoadAnnotationXML(string token, XmlDocument annotationXml) | Carica le annotazioni da XML |
XmlDocument GetAnnotationXML(string token) | Esporta le annotazioni della sessione come XML |
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default) | PDF con annotazioni incorporate |
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | Un PNG per pagina, annotazioni incorporate, scritte in directoryPath (creato se mancante); restituisce il numero di immagini scritte |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | ZIP di PNG per pagina con annotazioni incorporate |
Metadati DICOM
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)Restituisce i metadati dei tag DICOM per le sessioni aperte tramite il plugin DICOM; null per documenti non DICOM.
Helper di risorse — ReferenceCss / ReferenceScripts
Emette i tag <link>/<script> per le risorse incorporate servite da UseDoconutResources(), nell'ordine corretto di dipendenza. I bundle per funzionalità soggette a licenza, come ricerca e annotazione, vengono emessi solo quando la licenza le abilita, mantenendo l'interfaccia client coerente con il comportamento del server.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + visualizzatore + ricerca + annotazione
string ReferenceScripts(ScriptConfig? config = null)CssConfig flag: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (soggetto a ricerca), IncludeAnnotationCss (soggetto a annotazione).
ScriptConfig flag: IncludeJQuery (richiesto da tutti gli altri), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts e IncludeSearchBar (soggetto a ricerca), IncludeAnnotationScripts e IncludeAnnotationBar (soggetto a annotazione), EmitFeatureFlags (predefinito true: scrive anche uno script inline window.Doconut.features = { search, annotation, editor }; impostalo a false sotto una Content-Security-Policy che blocca gli script inline).
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))Questa pagina è stata utile?