GroupDocs.Annotation ist UI‑agnostisch. Es liest und schreibt Markup in Dokumenten und zeichnet nichts auf dem Bildschirm. Für eine Server‑Bibliothek ist das die richtige Trennung – und es wirft für alle, die sie übernehmen, eine Frage auf: Wie zeichnet eine Person tatsächlich die Anmerkung?

Die üblichen Antworten sind schwergewichtig: einen kommerziellen Viewer einbetten oder das Angular‑Demo übernehmen und dann versuchen, es zu erweitern. Es gibt eine leichtere Variante. Seitenbilder, ein Canvas und sechs Endpunkte – kein Viewer‑Komponente, kein Front‑End‑Framework, kein Build‑Schritt, kein CDN. Es läuft zudem völlig ohne ausgehenden Netzwerkzugriff, was wichtiger ist als früher.

Das Beispiel befindet sich auf GitHub:
browser-annotation-ui-net – dotnet run und ein Rechteck auf der Seite ziehen.

Die Idee in einem Absatz

Jede Seite einmal als PNG ohne Anmerkungen rendern und zwischenspeichern. Die Annotationsliste als Daten an den Browser senden. Das Canvas zeichnet das Markup über das Bild. Das Hinzufügen eines Kommentars ist dann ein kleiner Schreibvorgang in das Dokument plus ein Neuladen der Liste – kein erneutes Rendern der Seite – und das Markup bleibt auswählbar, anklickbar und beantwortbar, anstatt in ein Bild eingebettet zu werden.

Die Endpunkte

Methode Route Zweck
GET /api/documents/{name}/info Seitenanzahl und Größe jeder Seite in Punkten
GET /api/documents/{name}/pages/{n}/image PNG der Seite n
GET /api/documents/{name}/annotations jede Anmerkung als ein Rechteck in Seiteneinheiten
POST /api/documents/{name}/annotations eine hinzufügen
PUT /api/documents/{name}/annotations/{id} Nachricht ändern oder eine Antwort anhängen
DELETE /api/documents/{name}/annotations/{id} eine entfernen

Jeder Schreibvorgang gibt die vollständige Liste zurück, sodass der Browser nie überlegen muss, was der Server gerade hält.

Rendering

PreviewOptions previewOptions = new(page => File.Create(CachePath(name, page)))
{
    PreviewFormat = PreviewFormats.PNG,
    PageNumbers = new[] { pageNumber },   // 1-based
    RenderAnnotations = false,            // das Canvas zeichnet das Markup
    Resolution = 144
};

annotator.Document.GeneratePreview(previewOptions);

Vergleiche den Zeitstempel des zwischengespeicherten Bildes mit dem des Dokuments und rendere nur neu, wenn das Dokument tatsächlich geändert wurde.

Pixel als Eingabe, Seiteneinheiten als Ausgabe

Das Canvas behält sein Rechteck in Bild‑Pixeln und sendet die Größe des Bildes, auf dem es gezeichnet wurde – keinen Skalierungsfaktor:

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

Diese eine Entscheidung sorgt dafür, dass die UI korrekt bleibt, wenn sich die Vorschau‑Auflösung ändert, CSS das Bild skaliert oder jemand es auf einem Telefon öffnet. Der Server erledigt die Arithmetik:

double scaleX = page.Width / request.ImageWidth;
double scaleY = page.Height / request.ImageHeight;

annotator.Add(new AreaAnnotation
{
    PageNumber = page.PageNumber - 1,     // PageInfo ist 1‑basiert, Anmerkungen 0‑basiert
    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 wird vom oberen linken Eck der Seite gemessen – in derselben Richtung, in der der Browser misst – sodass ein gezeichnetes Rechteck mit einer Skalierung und ohne Spiegelung abgebildet wird.

Sende eine Rechtecksform an den Browser

Text‑Markup teilt diesen Ursprung nicht. HighlightAnnotation.Points und verwandte Werte werden vom unteren linken Eck gemessen. Auf dem Server konvertieren, sodass das Front‑End nur noch obere‑linke Rechtecke sieht:

x = minX;
y = page.Height - maxY;      // nach oben‑links umkehren
width = maxX - minX;
height = maxY - minY;

Macht man das, erscheint eine Hervorhebung, die in Word, Acrobat oder durch einen automatischen Prüfungsdurchlauf hinzugefügt wurde, an der richtigen Stelle in der UI, ohne dass das JavaScript etwas über PDF‑Geometrie wissen muss.

Schreibvorgänge verwenden Swap‑Dateien

Der Annotator hält die Quelle geöffnet und kann nicht über die Datei schreiben, die er gerade liest:

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

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

Um das gesamte Vorgehen herum einen pro‑Dokument‑Lock setzen. Zwei Anfragen, die gleichzeitig dieselbe Datei lesen, ändern und neu schreiben, verlieren eine der Änderungen.

Was dieses Design nicht löst

Es ist wichtig, das klar zu sagen, weil es entscheidet, ob man es so einsetzen kann:

  • Annotation ids change after a write. Sie werden zugewiesen, während das Dokument gelesen wird, und nicht darin gespeichert. Eine UI, die die Liste nach jeder Änderung neu lädt, ist in Ordnung. Ein Mehrbenutzer‑System sollte Anmerkungen in einer eigenen Tabelle halten und Import/Export nutzen, um sie in die Datei hinein‑ und herauszubewegen – so erhält man zudem ein Audit‑Trail und benutzerspezifische Sichtbarkeit.
  • The whole document is rewritten on every change. In Ordnung für einen 30‑Seiten‑Vertrag, falsch für ein 2.000‑Seiten‑Archiv.
  • There is no authentication. Jeder Aufrufer im Beispiel ist „Reviewer“.

Ausführen

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

Oder in einem Container, mit --network none, falls du beobachten willst, dass es völlig ohne ausgehenden Datenverkehr funktioniert:

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

Die Schritt‑für‑Schritt‑Version befindet sich in der Dokumentation:
Erstelle eine Annotations‑UI für deine Web‑App.
Wenn du bereits einen JavaScript‑PDF‑Viewer eingebettet hast, behalte ihn zur Anzeige und nutze diese Endpunkte ausschließlich für die Speicherung – keine der Geometrie‑Regeln ändert sich.