GroupDocs.Annotation est indépendant de l’interface utilisateur. Il lit et écrit les annotations à l’intérieur des documents et ne dessine rien à l’écran. Pour une bibliothèque serveur, c’est la bonne répartition — et cela laisse une question à tous ceux qui l’adoptent : comment une personne dessine-t-elle réellement l’annotation ?

Les réponses habituelles sont lourdes : intégrer un visualiseur commercial, ou adopter la démo Angular puis essayer de l’étendre. Il en existe une plus légère. Images de pages, un canvas et six points de terminaison — aucun composant de visualiseur, aucun framework front‑end, aucune étape de construction, aucun CDN. Elle fonctionne également sans aucun accès réseau sortant, ce qui compte plus qu’auparavant.

L’exemple est sur GitHub : browser-annotation-ui-net — dotnet run et faites glisser une boîte sur la page.

L’idée en un paragraphe

Rendre chaque page une fois en PNG sans annotations et la mettre en cache. Envoyer la liste des annotations au navigateur sous forme de données. Le canvas dessine les annotations sur l’image. Ajouter un commentaire devient alors une petite écriture dans le document plus un rechargement de la liste — pas un nouveau rendu de la page — et les annotations restent sélectionnables, cliquables et répondables au lieu d’être intégrées dans une image.

Les points de terminaison

Méthode Chemin Objectif
GET /api/documents/{name}/info nombre de pages et la taille de chaque page, en points
GET /api/documents/{name}/pages/{n}/image PNG de la page n
GET /api/documents/{name}/annotations toute annotation sous forme d’un rectangle en unités de page
POST /api/documents/{name}/annotations en ajouter une
PUT /api/documents/{name}/annotations/{id} modifier le message ou ajouter une réponse
DELETE /api/documents/{name}/annotations/{id} en supprimer une

Chaque écriture renvoie la liste complète, de sorte que le navigateur n’a jamais à se soucier de ce que le serveur détient maintenant.

Rendu

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

Comparez l’horodatage de l’image mise en cache avec celui du document et ne re‑rendez que lorsque le document a réellement changé.

Pixels en entrée, unités de page en sortie

Le canvas conserve son rectangle en pixels d’image et envoie la taille de l’image sur laquelle il a dessiné — pas un facteur d’échelle :

body: JSON.stringify({
    page: currentPage,
    x, y, width, height,
    imageWidth: img.clientWidth,
    imageHeight: img.clientHeight,
    message: window.prompt('Comment'),
    user: 'Reviewer'
})

Cette décision unique est ce qui maintient l’interface correcte lorsque la résolution de l’aperçu change, lorsque le CSS met à l’échelle l’image, ou lorsqu’une personne l’ouvre sur un téléphone. Le serveur effectue les calculs :

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 est mesuré depuis le coin supérieur gauche de la page — la même direction que le navigateur utilise — ainsi une boîte dessinée se mappe avec une échelle et sans inversion.

Envoyer une forme de rectangle au navigateur

Les annotations de texte ne partagent pas cette origine. HighlightAnnotation.Points et ses relatives sont mesurées depuis le coin inférieur gauche. Convertissez sur le serveur, de sorte que le front‑end ne voie jamais que des boîtes en haut‑gauche :

x = minX;
y = page.Height - maxY;      // flip to top-left
width = maxX - minX;
height = maxY - minY;

Faites cela et un surlignage ajouté dans Word, Acrobat ou par un automated review pass apparaît au bon endroit dans votre interface sans que le JavaScript ne connaisse la géométrie du PDF.

Les écritures utilisent des fichiers temporaires

L’annotateur garde la source ouverte et ne peut pas enregistrer par-dessus le fichier qu’il lit :

using (Annotator annotator = new Annotator(path))
{
    annotator.Add(annotation);
    annotator.Save(path + ".tmp");
}

File.Move(path + ".tmp", path, overwrite: true);
InvalidatePreviewCache(name);

Prenez un verrou par document autour de toute la séquence. Deux requêtes qui lisent, modifient et réécrivent le même fichier simultanément perdront l’une des modifications.

Ce que cette conception ne résout pas

Il vaut la peine de le dire clairement, car cela détermine si vous pouvez le livrer tel quel :

  • Les identifiants d’annotation changent après une écriture. Ils sont attribués pendant la lecture du document, pas stockés dans celui‑ci. Une interface qui recharge la liste après chaque modification convient. Un système multi‑utilisateur devrait conserver les annotations dans sa propre table et utiliser l’import/export pour les déplacer dans le fichier et en sortir — ce qui permet également d’obtenir une piste d’audit et une visibilité par utilisateur.
  • Le document entier est réécrit à chaque modification. Acceptable pour un contrat de 30 pages, inadapté pour une archive de 2 000 pages.
  • Il n’y a pas d’authentification. Chaque appelant dans l’exemple est « Reviewer ».

Exécuter

git clone https://github.com/groupdocs-annotation/browser-annotation-ui-net.git
cd browser-annotation-ui-net
dotnet run --project src/AnnotationUi

Ou dans un conteneur, avec --network none si vous voulez le voir fonctionner sans aucun trafic sortant :

docker build -t annotation-ui .
docker run --rm -p 8080:8080 annotation-ui

La version étape par étape se trouve dans la documentation : Build an annotation UI for your web app. Si vous avez déjà intégré un visualiseur PDF JavaScript, conservez‑le pour l’affichage et utilisez ces points de terminaison uniquement pour le stockage — aucune des règles de géométrie ne change.