Anotaciones

Agregar soporte de anotaciones al visor

Las anotaciones en Doconut funcionan en dos direcciones: los usuarios las dibujan en el widget del navegador y el servidor las persiste por página, o su código las crea programáticamente y las carga en una sesión abierta. De cualquier manera se renderizan en las páginas y pueden incorporarse en exportaciones PDF/PNG.

El soporte de anotaciones está controlado por la capacidad de licencia Annotation (concedida automáticamente bajo una licencia Temporal activa).

Habilitar la interfaz de anotaciones

La anotación es un módulo del Viewer, no una barra de herramientas independiente. La página completa debe incluir los recursos del Viewer, la barra de herramientas del Viewer, el montaje del Viewer y el objViewer inicializado; luego la Cinta de Anotaciones se monta y se adjunta a esa misma instancia.

Emita los paquetes de anotaciones junto con los paquetes del viewer — están controlados por licencia, por lo que las etiquetas solo aparecen cuando la capacidad está disponible:

html
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss     = true,
    IncludeAnnotationCss = true   // jquery-ui.min.css + annotationBar.css
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery             = true,
    IncludeViewerScripts      = true,
    IncludeAnnotationScripts  = true, // jquery-ui, raphael.js, annotation.js
    IncludeAnnotationBar      = true  // la cinta de anotación incrustada
}))

Mantenga la composición completa del Viewer visible en el marcado:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Controles del visor, incluyendo el botón que abre Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

El paquete de anotaciones genera el DOM de la Cinta dentro de annBarMount; no es necesario copiar sus botones o el marcado del diálogo. Inicialice docViewer primero, luego cree la Cinta solo cuando el servidor confirme que la anotación está licenciada:

html
<script>
    let annBar = null;
    let currentToken = '';

    const objViewer = $('#div_ctlDoc').docViewer({
        BasePath: 'doconut',
        ResPath: 'doconut-res/images',
        onAnnLoaded:    () => annBar?.handleAnnLoaded(),
        onAnnSaved:     () => annBar?.handleAnnSaved(),
        onAnnSaveError: () => annBar?.handleAnnSaveError(),
        onAnnClosed:    () => annBar?.handleAnnClosed(),
        onError:        (message) => console.error('Viewer error:', message)
    });

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token: currentToken }),
        onStatus: (message) => console.log(message),
        onToast: (message, type) => console.log(type, message),
        onLayout: () => requestAnimationFrame(() => objViewer.Refit())
    });
    annBar.attach(objViewer);
        </text>
    }
</script>

Sin la capacidad, ReferenceScripts omite el script de la Cinta, por lo que el if del lado del servidor mantiene una llamada doconutAnnotationBar(...) sin protección que podría romper la página.

Guardar desde la Cinta envía datos a través del middleware (AnnSave), que los almacena en la sesión del documento por página. La carga (AnnLoad) ocurre automáticamente cuando una página con anotaciones se renderiza. Los cuatro callbacks onAnn* mantienen la Cinta sincronizada con el ciclo de vida del viewer.

Ábrala y ciérrela desde cualquier barra de herramientas del Viewer propiedad del host:

javascript
annBar.open();
annBar.close();

La API pública de la Cinta es:

MétodoPropósito
attach(objViewer)Conecta la Cinta al viewer inicializado; se requiere una vez
open() / close()Entrar o salir del modo de edición de anotaciones
reset()Devuelve la Cinta a su estado cerrado, sin edición
isOpen() / annotating()Leer el estado de la Cinta / el estado de edición de anotaciones del viewer
reopenEditable()Recargar las anotaciones de la página actual como objetos editables
updateActionState()Actualizar la disponibilidad de los controles de guardar/eliminar después de cambios en el host
headerSlot()Obtener la ranura de extensión de encabezado opcional para controles propiedad del host

onStatus, onToast, onLayout, onEditStart y onEditEnd son callbacks opcionales del host. El objeto endpoints puede proporcionar adicionalmente exportPdf, exportPng, imageUpload y imageList; los controles sin un endpoint configurado permanecen ocultos. Para la secuencia de inicio combinada del Viewer, Search y Annotation, vea Inicio rápido.

El paquete de anotaciones agrega las herramientas de autoría del navegador, pero los datos siguen perteneciendo a la sesión del documento del lado del servidor identificada por el token. Reabrir la fuente crea una nueva sesión; persista el XML o el sobre de anotaciones codificado en su aplicación si las anotaciones deben sobrevivir más allá de la vida de la sesión.

Dos tipos de callback, cableados de dos maneras

El código de anotaciones usa dos estilos de callback, y cada uno falla silenciosamente cuando se cablea al revés:

  • onAnnLoaded, onAnnSaved, onAnnSaveError, onAnnClosed son opciones de docViewer({...}), como cualquier callback del visor.
  • Created, Changed, Deleted, y Properties son funciones globales encontradas por nombre: el id del visor se antepone al evento. Para el visor en #div_ctlDoc el id es ctlDoc, así que las funciones son ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted y ctlDoc_Properties. Una función con error ortográfico o renombrada simplemente nunca se llama.

SaveAnnotations() no devuelve si se guardó: el resultado llega a través de onAnnSaved o onAnnSaveError. El código que lee su valor de retorno nunca borra su bandera de "cambios no guardados".

Crear anotaciones en C#

Obtenga un gestor vinculado a la sesión abierta, añada anotaciones y cárguelas (con using Doconut.Annotations; para los tipos y using System.Drawing; para Rectangle/Color):

csharp
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
    // Vinculado a las dimensiones de página de la sesión abierta
    var manager = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // Un sello por página
    for (int page = 1; page <= pageCount; page++)
    {
        manager.Add(new StampAnnotation(page, new Rectangle(30, 20, 240, 90),
            $"PAGE {page}", 28, 4, Color.Maroon)
        {
            Opacity = 60,
            Rotate  = -8
        });
    }

    manager.Add(new NoteAnnotation(1, new Rectangle(420, 150, 220, 120),
        "Loaded from C# code.", Color.FromArgb(255, 255, 255, 170), 14));

    // Cargar en la sesión — el widget los recupera mediante AnnLoad y el
    // el renderizador los incrusta en exportaciones de imagen/PDF.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

Tipos de anotación

Todos los tipos residen en Doconut.Annotations y heredan de BaseAnnotation (número de página + Rectangle delimitador):

TipoNotas
StampAnnotationSello de texto con tamaño de fuente, borde, color; soporta Opacity, Rotate
NoteAnnotationNota adhesiva con texto, color de fondo, tamaño de fuente, TitleColor
RectangleAnnotationColores de borde y relleno, Title/ShowTitle
CircleAnnotationBorde + relleno, ShowBorder
EllipseAnnotationBorde + relleno, ShowBorder
TriangleAnnotationColor de borde, BackColor, ShowBorder
LineAnnotationLínea recta con ancho y color
ArrowAnnotationLínea con punta de flecha; Direction configurable (tipo ArrowDirection, puntos cardinales, predeterminado E)
FreehandAnnotationTrazo libre a partir de puntos codificados FreehandData
ImageAnnotationImagen desde una URL. Una URL relativa se resuelve contra el host de la solicitud cuando se añade la anotación; el servidor recupera la imagen solo al quemar — vea la nota de exportación abajo

La API de AnnotationManager

MiembroPropósito
Add(BaseAnnotation)Encolar una anotación
GetAnnotations() / GetAnnotations(int page)Inspeccionar lo que el gestor contiene
ClearAnnotations() / ClearAnnotations(int page)Eliminar todo / por página
GetAnnotationData() / GetAnnotationData(int page)Cadena de datos de anotación codificada — un sobre de cable Base64 (lo que consume el widget)
GetAnnotationXml()Forma XML

Viewer refleja las operaciones de carga/lectura contra una sesión: LoadAnnotationData(token, manager) o LoadAnnotationData(token, encodedData) (el sobre de cable Base64 de GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

Exportar con anotaciones incrustadas

csharp
// PDF de todas las páginas con anotaciones renderizadas sobre ellas
app.MapGet("/api/annotations/export-pdf", async (string token, Viewer viewer) =>
{
    byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100);
    return Results.File(pdf, "application/pdf", "export.pdf");
});

// O un ZIP de PNGs por página
app.MapGet("/api/annotations/export-png-zip", async (string token, Viewer viewer) =>
{
    byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100);
    return Results.File(zip, "application/zip", "annotations-png.zip");
});

Las exportaciones usan el mismo quemador que la renderización en pantalla, por lo que lo que los usuarios ven es lo que el archivo contiene — excepto las anotaciones de imagen, descritas a continuación.

Anotaciones de imagen en un host intranet exportan como "Image blocked"

El visor y la exportación obtienen la imagen de un ImageAnnotation desde diferentes lugares:

SuperficieQuién descarga la imagenEn un host intranet o de desarrollo
El visor en el navegadorEl navegador del usuarioLa imagen aparece
ExportAnnotationsToPdfAsync / …PngZipAsyncEl servidorUn marcador de posición rojo "Image blocked"

Cuando el servidor obtiene una imagen para incrustarla, rechaza direcciones que apuntan de nuevo a redes privadas: loopback (localhost, 127.0.0.1), 0.0.0.0, link-local (169.254.x.x), los rangos privados 10.x, 172.16–31.x y 192.168.x, NAT de nivel de operador (100.64.0.0/10), y direcciones IPv6 link-local y unique-local. Esto protege al servidor de ser usado para alcanzar sistemas internos mediante una URL de imagen manipulada, y no existe un interruptor para desactivarlo.

Una URL de imagen relativa se resuelve contra el host de la solicitud actual, por lo que en localhost, en un servidor intranet, o en cualquier sitio al que se acceda mediante una dirección privada, la imagen se muestra en el visor y la exportación contiene el marcador de posición en su lugar. Eso es la protección funcionando, no un fallo de renderizado. Si las exportaciones deben contener la imagen, sírvala desde un host con una dirección pública y use una URL absoluta. Un nombre de host que no pueda resolverse es rechazado de la misma manera; cualquier otro error de descarga muestra la URL y el mensaje de error en rojo donde estaría la imagen.

Flujo de trabajo de persistencia

  1. Abra el documento y obtenga su token.
  2. Cargue XML o datos codificados previamente almacenados en ese token.
  3. Permita que el widget lea y edite las anotaciones de la sesión.
  4. Recupere XML con GetAnnotationXML(token) cuando su aplicación decida persistir.
  5. Exporte PDF/PNG cuando se requiera un entregable aplanado.
  6. Cierre la sesión del documento.

No utilice el token opaco del visor como identificador permanente de anotaciones. Asocie los datos de anotaciones persistidos con sus propios identificadores de documento y de versión.

Notas de seguridad y renderizado

  • Las solicitudes de anotaciones usan la misma seguridad de sesión/token que las solicitudes de página.
  • Valide y controle cualquier URL de imagen suministrada por el usuario para evitar falsificaciones de solicitudes del lado del servidor.
  • Las exportaciones aplican la misma decisión de licencia/marca de agua personalizada que el renderizado de página en pantalla.
  • Las cargas útiles grandes de dibujo a mano alzada y las exportaciones de alta resolución aumentan el uso de memoria; pruebe documentos realistas y valores de zoom.

Solución de problemas

SíntomaVerificación
La cinta de anotaciones faltaCapacidad Annotation y las cuatro banderas CSS/script de anotación
La devolución de llamada de guardado informa un errorExpiración del token/sesión y middleware BasePath
ctlDoc_Created (u otra función de evento) nunca se ejecutaEl nombre de la función: id del visor + _ + evento, como función global
Las anotaciones C# no aparecenLa numeración de página comienza en uno y los datos se cargaron en el token activo
La anotación de imagen aparece en pantalla pero no en la exportaciónEl host de la imagen tiene una dirección privada o de loopback — ver arriba
El documento reabierto no tiene anotacionesPersista XML/datos fuera de la sesión del visor, luego cárguelos en el nuevo token

¿Fue útil esta página?