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 mai direttamente.

La precedente libreria .NET Standard esponeva un costruttore pubblico che accettava la cache di memoria, l'accessor del contesto HTTP e uno o più percorsi di licenza. Quel costruttore non esiste più; il grafo dei servizi fornisce tali dipendenze.

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 Viewer).

OpenDocumentAsync

Apre un documento e restituisce il token di sessione che il widget client utilizza per tutte le richieste successive. Ogni apertura è asincrona — non esiste un OpenDocument sincrono.

SovraccaricoQuando usarlo
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)Hai bisogno di 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 — guida il rilevamento del formato
csharp
// 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à plugin che non è più concessa. La scadenza del calendario senza un messaggio di rifiuto degrada al 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.

CloseDocument

text
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. Opzionale — la scadenza scorrevole esegue la stessa pulizia — ma è consigliata per documenti di grandi dimensioni.

GetPageCount

text
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.

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

La dimensione di pagina predefinita del documento renderizzata 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.

GetWorksheetNames

text
IReadOnlyList<string> GetWorksheetNames(string token)

Restituisce i nomi dei fogli di lavoro di un foglio di calcolo aperto, nell'ordine del workbook, oppure 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, compaiono solo quei fogli. Un foglio di lavoro non è sempre una singola 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.

Capability flags

MembroSignificato
bool IsSearchEnabledLa licenza corrente concede Search
bool IsAnnotationEnabledLa licenza corrente concede Annotation

Usa questi in una vista Razor per renderizzare un Ribbon con licenza solo quando il server lo fornirà effettivamente — vedi Avvio rapido.

DocOptions

Opzioni per apertura, indipendenti dal formato (namespace Doconut):

TipoProprietàPredefinitoDescrizione
stringPassword""Password per documenti protetti (copiata automaticamente nella configurazione del formato).
intImageResolution0Obsoleto. Conservato solo per compatibilità — impostare ImageResolution nella configurazione del formato invece.
stringWatermark""Testo personalizzato del watermark disegnato sulle pagine renderizzate. Stringa di formato: "^Text~Color~FontSize~FontName~Opacity~Angle", ad es. "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60Scadenza scorrevole della sessione in minuti.
boolIsSecuredtrueNon 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:

TipoProprietàPredefinitoDescrizione
boolIsWebFarmfalseObsoleto — non ha effetto. Pubblica il documento con DistributedDocumentPublisher.PublishAsync (o IDistributedPublishQueue.EnqueueAsync) e imposta FileShareConfig.RootPath invece. Nota la capitalizzazione — la libreria precedente scriveva questo IsWebfarm.
stringWebFarmPath""Obsoleto — non ha effetto. Usa FileShareConfig.RootPath, come descritto in Distribuzioni distribuite. Precedentemente scritto WebfarmPath.
boolEditModefalseRiservato per un flusso di lavoro di modifica distribuito separatamente; lascia false per il visualizzatore standard.

Custom watermark

DocOptions.Watermark utilizza sei campi separati da tilde. Un ^ opzionale all'inizio richiede il layout a tutti gli angoli:

text
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
CampoEsempioSignificato
Leading ^^Layout opzionale a tutti gli angoli. Senza di esso, viene usato il posizionamento normale del watermark.
TextConfidentialTesto renderizzato su ogni pagina. Non deve essere vuoto.
ColorRedColore denominato compreso dal livello di disegno.
FontSize24Dimensione del carattere; input numerico non valido ricade sul valore predefinito del renderer.
FontNameVerdanaFamiglia di caratteri richiesta. Assicurati che sia installata nell'ambiente di distribuzione.
Opacity80Valore byte da 0 a 255. Deve essere analizzato correttamente.
Angle-45Angolo 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 della licenza

Stato della licenzaValore personalizzato fornitoRisultato renderizzato
Licenza visualizzatore a pagamento validaNoPagina pulita
Licenza visualizzatore a pagamento validaSìFiligrana personalizzata
Visualizzatore base temporaneo/demo attivoNoPagina del visualizzatore base pulita
Visualizzatore base temporaneo/demo attivoSìFiligrana personalizzata quando si applica il percorso del visualizzatore base pulito
Licenza mancante, rifiutata, scaduta, versione errata o dominio non validoQualsiasiFiligrana di applicazione/valutazione; il valore personalizzato non la sovrascrive
Rendering del plugin secondo le regole di valutazioneQualsiasiFiligrana di valutazione

La stessa decisione viene applicata alle immagini delle pagine servite e alle esportazioni di annotazioni. L'output GIF animato viene marchiato fotogramma per fotogramma. Una filigrana personalizzata è quindi una funzionalità dell'applicazione concessa in 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; la sintesi è:

MembroScopo
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/involucro Base64 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, scritto 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

Ognuno di questi richiede il token di sessione. La forma GetAnnotationManager(pageWidth, pageHeight) senza sessione della libreria precedente rimane disponibile per la creazione di annotazioni al di fuori di una sessione, ma il loro caricamento richiede comunque un token.

Metadati DICOM

text
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

Il metodo è presente per l'allineamento dell'API, ma questo pacchetto non può fornire i tag tecnici DICOM: il lettore di metadati è distribuito solo con una build .NET 8. Restituisce null per le sessioni DICOM e non DICOM; in una sessione DICOM scrive anche un avviso una tantum che spiega la limitazione della piattaforma. Il rendering di pagine, fotogrammi e animazioni rimane supportato.

Helper delle risorse — ReferenceCss / ReferenceScripts

Emetti i tag <link>/<script> per le risorse incorporate servite da UseDoconutResources(), nell'ordine corretto di dipendenza. I bundle per le funzionalità soggette a licenza, come la ricerca e le annotazioni, vengono emessi solo quando la licenza le abilita, mantenendo l'interfaccia client coerente con il comportamento del server.

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + visualizzatore + ricerca + annotazione
string ReferenceScripts(ScriptConfig? config = null)

Flag CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (soggette a ricerca), IncludeAnnotationCss (soggette a annotazione).

Flag ScriptConfig: IncludeJQuery (richiesto da tutti gli altri), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts e IncludeSearchBar (soggette a ricerca), IncludeAnnotationScripts e IncludeAnnotationBar (soggette a annotazione), EmitFeatureFlags (predefinito true: scrive anche uno script inline window.Doconut.features = { search, annotation, editor }; impostalo su false sotto una Content-Security-Policy che blocca gli script inline).

html
@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

Questi helper sono il modo supportato per fornire le risorse del browser. Le applicazioni che hanno copiato docViewer.js, documentLinks.js e docViewer.UI.js in wwwroot dovrebbero rimuovere tali copie una volta che la pagina viene renderizzata dai tag emessi.

Questa pagina è stata utile?