GroupDocs.Annotation è UI‑agnostic. Legge e scrive markup all’interno dei documenti e non disegna nulla su uno schermo. Per una libreria server questo è il giusto compromesso — e lascia una domanda per tutti coloro che la adottano: come fa una persona a disegnare effettivamente l’annotazione?

Le risposte abituali sono pesanti: incorporare un visualizzatore commerciale, o adottare la demo Angular e poi cercare di estenderla. Ce n’è una più leggera. Immagini delle pagine, una canvas e sei endpoint — nessun componente visualizzatore, nessun framework front‑end, nessun passaggio di build, nessun CDN. Funziona anche senza alcun accesso di rete in uscita, cosa che ora conta più di prima.

Il campione è su GitHub: browser-annotation-ui-net — dotnet run e trascina un riquadro sulla pagina.

L’idea in un paragrafo

Renderizza ogni pagina una volta come PNG senza annotazioni e memorizzala nella cache. Invia l’elenco delle annotazioni al browser come dati. La canvas disegna il markup sopra l’immagine. Aggiungere un commento è quindi una piccola scrittura sul documento più un ricaricamento dell’elenco — non un nuovo rendering della pagina — e il markup rimane selezionabile, cliccabile e rispondibile invece di essere incorporato in un’immagine.

Gli endpoint

Metodo Percorso Scopo
GET /api/documents/{name}/info conteggio delle pagine e la dimensione di ogni pagina, in punti
GET /api/documents/{name}/pages/{n}/image PNG della pagina n
GET /api/documents/{name}/annotations ogni annotazione come un rettangolo in unità di pagina
POST /api/documents/{name}/annotations aggiungerne una
PUT /api/documents/{name}/annotations/{id} modificare il messaggio o aggiungere una risposta
DELETE /api/documents/{name}/annotations/{id} rimuoverne una

Ogni scrittura restituisce l’elenco completo, così il browser non deve mai ragionare su ciò che il server ora contiene.

Rendering

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

Confronta il timestamp dell’immagine nella cache con quello del documento e rigenera solo quando il documento è effettivamente cambiato.

Pixel in, unità di pagina out

La canvas mantiene il suo rettangolo in pixel dell’immagine e invia la dimensione dell’immagine su cui ha disegnato — non un fattore di scala:

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

Questa decisione è ciò che mantiene l’interfaccia corretta quando la risoluzione dell’anteprima cambia, quando il CSS scala l’immagine, o quando qualcuno la apre su un telefono. Il server esegue l’aritmetica:

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 è misurato dall’angolo in alto a sinistra della pagina — la stessa direzione in cui misura il browser — così un riquadro disegnato si mappa con una scala e senza inversione.

Invia una forma di rettangolo al browser

Il markup del testo non condivide quell’origine. HighlightAnnotation.Points e i suoi correlati sono misurati dall’angolo in basso a sinistra. Converti sul server, così il front‑end vede sempre solo riquadri in alto a sinistra:

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

Fallo e un evidenziatore aggiunto in Word, in Acrobat, o da un passaggio di revisione automatizzato appare nel posto giusto nella tua UI senza che il JavaScript sappia nulla della geometria PDF.

Le scritture scambiano file

L’annotatore mantiene la sorgente aperta e non può salvare sopra il file che sta leggendo:

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

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

Prendi un lock per documento attorno all’intera sequenza. Due richieste che leggono, modificano e riscrivono lo stesso file contemporaneamente perderanno una delle modifiche.

Ciò che questo design non risolve

Vale la pena dirlo chiaramente, perché decide se puoi distribuirlo così com’è:

  • Gli ID delle annotazioni cambiano dopo una scrittura. Vengono assegnati mentre il documento è letto, non sono memorizzati in esso. Un UI che ricarica l’elenco dopo ogni modifica va bene. Un sistema multi‑utente dovrebbe tenere le annotazioni in una propria tabella e usare importazione ed esportazione per spostarle dentro e fuori dal file — il che è anche il modo per ottenere un tracciato di audit e visibilità per utente.
  • L’intero documento viene riscritto ad ogni modifica. Va bene per un contratto di 30 pagine, sbagliato per un archivio di 2.000 pagine.
  • Non c’è autenticazione. Ogni chiamante nel campione è “Reviewer”.

Eseguilo

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

Oppure in un container, con --network none se vuoi osservare il suo funzionamento senza alcun traffico in uscita:

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

La versione passo‑passo è nella documentazione: Crea un’interfaccia di annotazione per la tua app web. Se hai già incorporato un visualizzatore PDF JavaScript, mantienilo per la visualizzazione e usa questi endpoint solo per l’archiviazione — nessuna delle regole di geometria cambia.