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.

SovraccaricoQuando 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
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à 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

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

OttieniConteggioPagine

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.

OttieniDimensioniPagina

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.

OttieniNomiFogliDiLavoro

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

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.

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 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 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.
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
Prefisso ^^Layout opzionale a tutti gli angoli. Senza di esso, viene usato il posizionamento normale della filigrana.
TestoConfidentialTesto renderizzato su ogni pagina. Non deve essere vuoto.
ColoreRedColore nominato compreso dal livello di disegno.
DimensioneFont24Dimensione del carattere; input numerico non valido ricade sul valore predefinito del renderer.
NomeFontVerdanaFamiglia di caratteri richiesta. Assicurati che sia installata nell'ambiente di distribuzione.
Opacità80Valore byte da 0 a 255. Deve essere analizzato correttamente.
Angolo-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 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 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 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 è:

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/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)

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.

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

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?