Visualizzatore

La classe principale di visualizzazione dei 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 della sessione, quindi la disposizione del servizio non potrebbe mai chiudere un documento aperto (vedi Core Concepts → How the Viewer Works).

OpenDocumentAsync

Apre un documento e restituisce il token di sessione che il widget client utilizza per tutte le richieste successive.

SovraccaricoQuando usare
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 — essa 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 è rifiutata (il messaggio contiene il motivo del rifiuto), o il formato necessita di una capacità plugin 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.

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

GetWorksheetNames

text
IReadOnlyList<string> GetWorksheetNames(string token)

Restituisce i nomi dei fogli di lavoro di un foglio di calcolo aperto, nell'ordine della cartella di lavoro, o una lista vuota quando il documento aperto non è un foglio di calcolo.

Solo i fogli di lavoro renderizzati sono elencati: 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 pagina — uno molto grande è 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 in 26.9.0.

Flag di capacità

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 Guida rapida.

Opzioni Doc

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 della filigrana 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 fondamentali → 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.
stringWebFarmPath""Obsoleto — non ha effetto. Usa FileShareConfig.RootPath invece.
boolEditModefalseRiservato 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
^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
^ iniziale^Layout opzionale a tutti gli angoli. Senza di esso, viene usato il posizionamento normale della filigrana.
TextConfidentialTesto renderizzato su ogni pagina. Non deve essere vuoto.
ColorRedColore nominato compreso dal livello di disegno.
FontSize24Dimensione del carattere; input numerico non valido ricade al 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 al valore predefinito.

Il parser si aspetta esattamente sei campi dopo il ^ opzionale. Una definizione non valida viene sostituita dal fallback visibile Invalid Watermark del SDK invece di scomparire silenziosamente.

Decisione di licenza

Stato della licenzaValore personalizzato fornitoRisultato renderizzato
Licenza viewer a pagamento validaNoPagina pulita
Licenza viewer a pagamento validaSìFiligrana personalizzata
Viewer base Temporaneo/Demo attivoNoPagina del viewer base pulita
Viewer base Temporaneo/Demo attivoSìFiligrana personalizzata quando si applica il percorso del viewer base pulito
Licenza mancante, rifiutata, scaduta, versione errata o dominio non validoQualsiasiFiligrana di enforcement/valutazione; il valore personalizzato non la sovrascrive
Rendering del plugin sotto regole di valutazioneQualsiasiFiligrana di valutazione

La stessa decisione viene applicata alle immagini delle pagine servite e alle esportazioni di annotazioni. L'output GIF animato è 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; l’interfaccia è:

MembroScopo
AnnotationManager GetAnnotationManager(string token)Gestore legato alle dimensioni della pagina della sessione aperta
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)Gestore con dimensioni della pagina esplicite
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)Gestore 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

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

Il metodo è presente per allineamento API, ma il visualizzatore DICOM .NET 6 non può fornire tag tecnici. 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 di risorse — ReferenceCss / ReferenceScripts

Emetti i tag <link>/<script> per le risorse incorporate servite da UseDoconutResources(), nell’ordine di dipendenza corretto. I bundle per funzionalità soggette a licenza, come ricerca e annotazione, sono 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 (search-gated), IncludeAnnotationCss (annotation-gated).

Flag ScriptConfig: IncludeJQuery (richiesto da tutti gli altri), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts e IncludeSearchBar (search-gated), IncludeAnnotationScripts e IncludeAnnotationBar (annotation-gated), 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 }))

Questa pagina è stata utile?