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.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:
<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:
<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:
annBar.open();
annBar.close();La API pública de la Cinta es:
| Método | Propó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,onAnnClosedson opciones dedocViewer({...}), como cualquier callback del visor.Created,Changed,Deleted, yPropertiesson funciones globales encontradas por nombre: el id del visor se antepone al evento. Para el visor en#div_ctlDocel id esctlDoc, así que las funciones sonctlDoc_Created,ctlDoc_Changed,ctlDoc_DeletedyctlDoc_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):
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):
| Tipo | Notas |
|---|---|
StampAnnotation | Sello de texto con tamaño de fuente, borde, color; soporta Opacity, Rotate |
NoteAnnotation | Nota adhesiva con texto, color de fondo, tamaño de fuente, TitleColor |
RectangleAnnotation | Colores de borde y relleno, Title/ShowTitle |
CircleAnnotation | Borde + relleno, ShowBorder |
EllipseAnnotation | Borde + relleno, ShowBorder |
TriangleAnnotation | Color de borde, BackColor, ShowBorder |
LineAnnotation | Línea recta con ancho y color |
ArrowAnnotation | Línea con punta de flecha; Direction configurable (tipo ArrowDirection, puntos cardinales, predeterminado E) |
FreehandAnnotation | Trazo libre a partir de puntos codificados FreehandData |
ImageAnnotation | Imagen 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
| Miembro | Propó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
// 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:
| Superficie | Quién descarga la imagen | En un host intranet o de desarrollo |
|---|---|---|
| El visor en el navegador | El navegador del usuario | La imagen aparece |
ExportAnnotationsToPdfAsync / …PngZipAsync | El servidor | Un 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
- Abra el documento y obtenga su token.
- Cargue XML o datos codificados previamente almacenados en ese token.
- Permita que el widget lea y edite las anotaciones de la sesión.
- Recupere XML con
GetAnnotationXML(token)cuando su aplicación decida persistir. - Exporte PDF/PNG cuando se requiera un entregable aplanado.
- 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íntoma | Verificación |
|---|---|
| La cinta de anotaciones falta | Capacidad Annotation y las cuatro banderas CSS/script de anotación |
| La devolución de llamada de guardado informa un error | Expiración del token/sesión y middleware BasePath |
ctlDoc_Created (u otra función de evento) nunca se ejecuta | El nombre de la función: id del visor + _ + evento, como función global |
| Las anotaciones C# no aparecen | La 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ón | El host de la imagen tiene una dirección privada o de loopback — ver arriba |
| El documento reabierto no tiene anotaciones | Persista XML/datos fuera de la sesión del visor, luego cárguelos en el nuevo token |
¿Fue útil esta página?