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.