GroupDocs.Annotation es independiente de la UI. Lee y escribe marcas dentro de los documentos y no dibuja nada en una pantalla. Para una biblioteca de servidor esa es la división correcta — y deja una pregunta para todos los que la adoptan: ¿cómo dibuja realmente una persona la anotación?
Las respuestas habituales son pesadas: incrustar un visor comercial, o adoptar la demo de Angular y luego intentar ampliarla. Hay una más ligera. Imágenes de página, un canvas y seis endpoints — sin componente de visor, sin framework front-end, sin paso de compilación, sin CDN. También funciona sin ningún acceso de red saliente, lo cual ahora importa más que antes.
El ejemplo está en GitHub: browser-annotation-ui-net — dotnet run y arrastra un cuadro en la página.
La idea en un párrafo
Renderiza cada página una vez como PNG sin anotaciones y guárdala en caché. Envía la lista de anotaciones al navegador como datos. El canvas dibuja la marca sobre la imagen. Añadir un comentario es entonces una pequeña escritura en el documento más una recarga de la lista — no una re‑renderización de la página — y la marca permanece seleccionable, clicable y respondible en lugar de estar incrustada en una imagen.
Los endpoints
| Método | Ruta | Propósito |
|---|---|---|
GET |
/api/documents/{name}/info |
recuento de páginas y el tamaño de cada página, en puntos |
GET |
/api/documents/{name}/pages/{n}/image |
PNG de la página n |
GET |
/api/documents/{name}/annotations |
cada anotación como un rectángulo en unidades de página |
POST |
/api/documents/{name}/annotations |
añadir una |
PUT |
/api/documents/{name}/annotations/{id} |
cambiar el mensaje o añadir una respuesta |
DELETE |
/api/documents/{name}/annotations/{id} |
eliminar una |
Cada escritura devuelve la lista completa, de modo que el navegador nunca tiene que razonar sobre lo que el servidor tiene ahora.
Renderizado
PreviewOptions previewOptions = new(page => File.Create(CachePath(name, page)))
{
PreviewFormat = PreviewFormats.PNG,
PageNumbers = new[] { pageNumber }, // 1-based
RenderAnnotations = false, // the canvas draws the markup
Resolution = 144
};
annotator.Document.GeneratePreview(previewOptions);
Compara la marca de tiempo de la imagen en caché con la del documento y vuelve a renderizar solo cuando el documento realmente haya cambiado.
Píxeles de entrada, unidades de página de salida
El canvas mantiene su rectángulo en píxeles de imagen y envía el tamaño de la imagen sobre la que dibujó — no un factor de escala:
body: JSON.stringify({
page: currentPage,
x, y, width, height,
imageWidth: img.clientWidth,
imageHeight: img.clientHeight,
message: window.prompt('Comment'),
user: 'Reviewer'
})
Esa decisión es lo que mantiene la UI correcta cuando cambia la resolución de la vista previa, cuando CSS escala la imagen, o cuando alguien la abre en un teléfono. El servidor realiza la aritmética:
double scaleX = page.Width / request.ImageWidth;
double scaleY = page.Height / request.ImageHeight;
annotator.Add(new AreaAnnotation
{
PageNumber = page.PageNumber - 1, // PageInfo is 1-based, annotations are 0-based
Box = new Rectangle(
(float)(request.X * scaleX), (float)(request.Y * scaleY),
(float)(request.Width * scaleX), (float)(request.Height * scaleY)),
BackgroundColor = 0xFFE699,
PenColor = 0xE08C00,
Opacity = 0.35,
Message = request.Message,
User = new User { Id = 1, Name = request.User, Role = Role.Editor }
});
AreaAnnotation.Box se mide desde la esquina superior izquierda de la página — la misma dirección en que lo mide el navegador — por lo que un cuadro dibujado se mapea con una escala y sin inversión.
Enviar una forma de rectángulo al navegador
Las marcas de texto no comparten ese origen. HighlightAnnotation.Points y sus relativos se miden desde la esquina inferior izquierda. Convierte en el servidor, de modo que el front end solo vea cajas superiores izquierdas:
x = minX;
y = page.Height - maxY; // flip to top-left
width = maxX - minX;
height = maxY - minY;
Haz esto y un resaltado añadido en Word, en Acrobat, o mediante una revisión automatizada aparecerá en el lugar correcto en tu UI sin que el JavaScript sepa nada sobre la geometría del PDF.
Las escrituras usan archivos temporales
El anotador mantiene la fuente abierta y no puede sobrescribir el archivo que está leyendo:
using (Annotator annotator = new Annotator(path))
{
annotator.Add(annotation);
annotator.Save(path + ".tmp");
}
File.Move(path + ".tmp", path, overwrite: true);
InvalidatePreviewCache(name);
Toma un bloqueo por documento alrededor de toda la secuencia. Dos solicitudes que lean, cambien y reescriban el mismo archivo simultáneamente perderán uno de los cambios.
Lo que este diseño no resuelve
Vale la pena decirlo claramente, porque decide si puedes entregarlo tal como está:
- Los IDs de anotación cambian después de una escritura. Se asignan mientras se lee el documento, no se almacenan en él. Una UI que recargue la lista después de cada cambio está bien. Un sistema multi‑usuario debería mantener las anotaciones en su propia tabla y usar importación y exportación para moverlas dentro y fuera del archivo — lo cual también permite obtener un registro de auditoría y visibilidad por usuario.
- Todo el documento se reescribe en cada cambio. Está bien para un contrato de 30 páginas, es incorrecto para un archivo de 2 000 páginas.
- No hay autenticación. Cada llamador en el ejemplo es “Reviewer”.
Ejecutarlo
git clone https://github.com/groupdocs-annotation/browser-annotation-ui-net.git
cd browser-annotation-ui-net
dotnet run --project src/AnnotationUi
O en un contenedor, con --network none si deseas observar su funcionamiento sin salida de red alguna:
docker build -t annotation-ui .
docker run --rm -p 8080:8080 annotation-ui
La versión paso a paso está en la documentación: Construye una UI de anotación para tu aplicación web. Si ya incrustas un visor PDF en JavaScript, mantenlo para la visualización y usa estos endpoints solo para el almacenamiento — ninguna de las reglas de geometría cambia.