Visor

La clase principal del visor de documentos

Viewer (namespace Doconut) es el punto de entrada público para abrir documentos desde páginas Razor, controladores MVC, componentes Blazor o APIs mínimas. Es sellado, registrado como un servicio transitorio por AddDoconut(), y resuelto mediante inyección de constructor — nunca lo construyas directamente.

Viewer no mantiene estado por solicitud y deliberadamente no implementa IDisposable: las sesiones de documentos viven de forma independiente en la caché de sesiones, por lo que disponer del servicio nunca podría cerrar un documento abierto (ver Conceptos Básicos → Cómo Funciona el Visor).

OpenDocumentAsync

Abre un documento y devuelve el token de sesión que el widget cliente utiliza para todas las solicitudes posteriores.

SobrecargaUsar cuando
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)Apertura desde disco con detección automática de formato y la configuración predeterminada del formato
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)Necesitas opciones de renderizado por formato (PdfConfig, WordConfig, …)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)El documento no es un archivo en disco (carga, base de datos, blob). fileInfo debe llevar la extensión correcta — es lo que impulsa la detección de formato
csharp
// Apertura simple
string token = await viewer.OpenDocumentAsync(path);

// Con configuración y opciones por formato
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// Desde una carga
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

Excepciones a manejar:

  • LicenseException — una licencia encontrada es rechazada (el mensaje lleva la razón del rechazo), o el formato necesita una capacidad de complemento que ya no está concedida. La expiración del calendario sin un mensaje de rechazo degrada a renderizado con marca de agua en lugar de lanzar una excepción.
  • FormatNotSupportedException — Document format '<extension>' is not supported.
  • InvalidDataException — el contenido del archivo está corrupto o no coincide con su extensión.

CloseDocument

text
void CloseDocument(string token)

Elimina la sesión de la caché (disponiendo del motor de documentos inmediatamente), borra el marcador de seguridad y revoca la concesión de acceso. Opcional — la expiración deslizante realiza la misma limpieza — pero se recomienda para documentos grandes.

GetPageCount

text
int GetPageCount(string token)

Número total de páginas de la sesión abierta. Lanza InvalidOperationException (Document session not found. Please re-open document.) si el token es desconocido o ha expirado, y ArgumentException para un token vacío.

GetPageDimensions

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

El tamaño de página predeterminado renderizado del documento al 100 % de zoom — el espacio de coordenadas para anotaciones construidas en código. page se acepta por compatibilidad; el resultado es el valor predeterminado del documento. Lanza InvalidOperationException (Document session not found. Please re-open document.) si el token es desconocido o ha expirado, y ArgumentException para un token vacío.

GetWorksheetNames

text
IReadOnlyList<string> GetWorksheetNames(string token)

Devuelve los nombres de las hojas de cálculo de una hoja de cálculo abierta, en orden de libro, o una lista vacía cuando el documento abierto no es una hoja de cálculo.

Solo se enumeran las hojas de cálculo renderizadas: las hojas ocultas y vacías se excluyen, y cuando ExcelConfig.SheetNames restringe el renderizado, solo aparecen esas hojas. Una hoja de cálculo no siempre corresponde a una página — una muy grande se renderiza en varias páginas. Lanza InvalidOperationException (Document session not found. Please re-open document.) si el token es desconocido o ha expirado, y ArgumentException para un token vacío.

Añadido en 26.9.0.

Banderas de capacidad

MiembroSignificado
bool IsSearchEnabledLa licencia actual otorga Search
bool IsAnnotationEnabledLa licencia actual otorga Annotation

Utilice estos en una vista Razor para renderizar una cinta con licencia solo cuando el servidor realmente la sirva — vea Inicio rápido.

Opciones de documento

Opciones por apertura, independientes del formato (namespace Doconut):

TipoPropiedadValor predeterminadoDescripción
stringPassword""Contraseña para documentos protegidos (copiada automáticamente en la configuración de formato).
intImageResolution0Obsoleto. Conservado solo por compatibilidad — establezca ImageResolution en la configuración de formato en su lugar.
stringWatermark""Texto de marca de agua personalizada dibujado en las páginas renderizadas. Cadena de formato: "^Text~Color~FontSize~FontName~Opacity~Angle", p. ej. "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60Expiración deslizante de la sesión en minutos.
boolIsSecuredtrueNo se aplica actualmente — reservado. La vinculación de tokens se controla globalmente mediante DoconutOptions.UnsafeMode (ver Conceptos básicos → Sesiones y seguridad).

La clase también expone propiedades especializadas que están intencionalmente fuera del flujo de visualización normal de un solo host:

TipoPropiedadValor predeterminadoDescripción
boolIsWebFarmfalseObsoleto — no tiene efecto. Publique el documento con DistributedDocumentPublisher.PublishAsync (o IDistributedPublishQueue.EnqueueAsync) y establezca FileShareConfig.RootPath en su lugar.
stringWebFarmPath""Obsoleto — no tiene efecto. Use FileShareConfig.RootPath en su lugar.
boolEditModefalseReservado para el flujo de trabajo del Editor distribuido por separado; deje false para el visor estándar.

Marca de agua personalizada

DocOptions.Watermark usa seis campos separados por tildes. Un ^ opcional al inicio solicita el diseño de todas las esquinas:

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
    });
CampoEjemploSignificado
Prefijo ^^Diseño opcional de todas las esquinas. Sin él, se usa la colocación normal de la marca de agua.
TextoConfidentialTexto renderizado en cada página. No debe estar vacío.
ColorRedColor nombrado entendido por la capa de dibujo.
TamañoFuente24Tamaño de fuente; una entrada numérica no válida vuelve al valor predeterminado del renderizador.
NombreFuenteVerdanaFamilia de fuente solicitada. Asegúrese de que esté instalada en el entorno de despliegue.
Opacidad80Valor de byte de 0 a 255. Debe analizarse correctamente.
Ángulo-45Ángulo de rotación en grados; una entrada numérica no válida vuelve al valor predeterminado.

El analizador espera exactamente seis campos después del ^ opcional. Una definición no válida se reemplaza por el fallback visible Invalid Watermark del SDK en lugar de desaparecer silenciosamente.

Decisión de licencia

Estado de la licenciaValor personalizado suministradoResultado renderizado
Licencia de visor pagado válidaNoPágina limpia
Licencia de visor pagado válidaSíMarca de agua personalizada
Visor base Temporal/Demo activoNoPágina de visor base limpia
Visor base Temporal/Demo activoSíMarca de agua personalizada cuando se aplica la ruta del visor base limpio
Licencia faltante, rechazada, expirada, de versión incorrecta o de dominio inválidoCualquieraMarca de agua de aplicación/evaluación; el valor personalizado no la sobrescribe
Renderizado de complemento bajo reglas de evaluaciónCualquieraMarca de agua de evaluación

La misma decisión se aplica a las imágenes de página servidas y a las exportaciones de anotaciones. La salida GIF animada se marca fotograma a fotograma. Por lo tanto, una marca de agua personalizada es una característica de aplicación con licencia, no una forma de reemplazar o suprimir la marca de agua de evaluación.

API de anotaciones

Carga y exportación de anotaciones del lado del servidor. La guía completa está en Guías → Anotaciones; la superficie es:

MiembroPropósito
AnnotationManager GetAnnotationManager(string token)Administrador vinculado a las dimensiones de página de la sesión abierta
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)Administrador con dimensiones de página explícitas
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)Administrador independiente de la sesión
void LoadAnnotationData(string token, AnnotationManager manager)Cargar anotaciones construidas en C# en la sesión
void LoadAnnotationData(string token, string annotationData)Cargar anotaciones desde la página codificada/envoltorio Base64 devuelto por AnnotationManager.GetAnnotationData()
void LoadAnnotationXML(string token, XmlDocument annotationXml)Cargar anotaciones desde XML
XmlDocument GetAnnotationXML(string token)Exportar las anotaciones de la sesión como XML
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)PDF con anotaciones incrustadas
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)Un PNG por página, anotaciones incrustadas, escrito a directoryPath (creado si falta); devuelve el número de imágenes escritas
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)ZIP de PNGs por página con anotaciones incrustadas

Metadatos DICOM

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

Devuelve los metadatos de etiquetas DICOM para sesiones abiertas a través del complemento DICOM; null para documentos que no son DICOM.

Ayudantes de recursos — ReferenceCss / ReferenceScripts

Emite las etiquetas <link>/<script> para los recursos incrustados servidos por UseDoconutResources(), en el orden de dependencia correcto. Los paquetes para funciones limitadas por licencia, como búsqueda y anotación, se emiten solo cuando la licencia las habilita, manteniendo la interfaz de usuario del cliente coherente con el comportamiento del servidor.

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

CssConfig flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (limitado por búsqueda), IncludeAnnotationCss (limitado por anotación).

ScriptConfig flags: IncludeJQuery (requerido por todos los demás), IncludeBootstrap, IncludeViewerScripts (núcleo: docViewer.js + divisor + enlaces), IncludeSearchScripts y IncludeSearchBar (limitado por búsqueda), IncludeAnnotationScripts y IncludeAnnotationBar (limitado por anotación), EmitFeatureFlags (predeterminado true: también escribe un script window.Doconut.features = { search, annotation, editor } en línea; configúralo a false bajo una Política de Seguridad de Contenido que bloquee scripts en línea).

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

¿Fue útil esta página?