GroupDocs.Annotation je nezávislý na UI. Čte a zapisuje značky uvnitř dokumentů a nic nevykresluje na obrazovku. Pro serverovou knihovnu je to správné rozdělení — a zanechává jednu otázku pro všechny, kteří ji používají: jak člověk ve skutečnosti vytvoří anotaci?

Obvyklé odpovědi jsou těžkopádné: vložit komerční prohlížeč, nebo použít Angular demo a pak se ho snažit rozšířit. Existuje lehčí varianta. Obrázky stránek, plátno a šest koncových bodů — žádná komponenta prohlížeče, žádný front‑end framework, žádný build krok, žádný CDN. Navíc běží bez jakéhokoli odchozího síťového přístupu, což je důležitější než dříve.

Ukázka je na GitHubu:
browser-annotation-ui-net — dotnet run a přetáhněte rámeček na stránku.

Myšlenka v jednom odstavci

Vygenerujte každou stránku jednou jako PNG bez anotací a uložte ji do cache. Pošlete seznam anotací do prohlížeče jako data. Plátno vykreslí značky nad obrázkem. Přidání komentáře pak představuje malý zápis do dokumentu plus znovunačtení seznamu — ne přegenerování stránky — a značky zůstávají vybratelné, klikatelné a odpověditelné místo aby byly vryté do obrázku.

Koncové body

Metoda Cesta Účel
GET /api/documents/{name}/info počet stránek a velikost každé stránky v bodech
GET /api/documents/{name}/pages/{n}/image PNG stránky n
GET /api/documents/{name}/annotations každá anotace jako jeden obdélník v jednotkách stránky
POST /api/documents/{name}/annotations přidat jednu
PUT /api/documents/{name}/annotations/{id} změnit zprávu nebo přidat odpověď
DELETE /api/documents/{name}/annotations/{id} odstranit jednu

Každý zápis vrací celý seznam, takže prohlížeč nikdy nemusí uvažovat o tom, co server nyní drží.

Renderování

PreviewOptions previewOptions = new(page => File.Create(CachePath(name, page)))
{
    PreviewFormat = PreviewFormats.PNG,
    PageNumbers = new[] { pageNumber },   // 1-based
    RenderAnnotations = false,            // plátno vykreslí značky
    Resolution = 144
};

annotator.Document.GeneratePreview(previewOptions);

Porovnejte časové razítko uloženého obrázku s časovým razítkem dokumentu a přegenerujte jen tehdy, když se dokument skutečně změnil.

Pixely dovnitř, jednotky stránky ven

Plátno uchovává svůj obdélník v pixelech obrázku a posílá velikost obrázku, na který kreslilo — ne měřítko:

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

To jedno rozhodnutí udržuje UI správné, když se mění rozlišení náhledu, když CSS mění velikost obrázku, nebo když si ho někdo otevře na telefonu. Server provede aritmetiku:

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

annotator.Add(new AreaAnnotation
{
    PageNumber = page.PageNumber - 1,     // PageInfo je 1‑based, anotace jsou 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 měří od levého horního rohu stránky — stejným směrem, jakým měří prohlížeč — takže nakreslený rámeček se mapuje se škálou a bez převrácení.

Odeslat jeden tvar obdélníku do prohlížeče

Textové značky nesdílejí tento počátek. HighlightAnnotation.Points a související položky se měří od levého dolního rohu. Převádějte na serveru, aby front‑end viděl jen levé horní rámečky:

x = minX;
y = page.Height - maxY;      // převrátit na levý horní
width = maxX - minX;
height = maxY - minY;

Udělejte tak a zvýraznění přidané ve Wordu, v Acrobat nebo pomocí automatizovaného revizního průchodu se objeví na správném místě ve vašem UI, aniž by JavaScript věděl něco o geometrii PDF.

Zápisy používají swap soubory

Annotátor drží zdroj otevřený a nemůže přepsat soubor, který čte:

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

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

Zabalte celou sekvenci do zámku na úrovni dokumentu. Dvě požadavky, které najednou čtou, mění a přepisují stejný soubor, ztratí jednu ze změn.

Co tento návrh neřeší

Stojí za to říct otevřeně, protože to rozhoduje, zda jej můžete nasadit tak, jak je:

  • ID anotací se po zápisu změní. Přidělují se během čtení dokumentu, ne ukládají se v něm. UI, které po každé změně znovu načte seznam, je v pořádku. Víceuživatelský systém by měl anotace uchovávat ve vlastní tabulce a používat import a export pro jejich přesun dovnitř a ven ze souboru — což je také způsob, jak získat auditní stopu a viditelnost podle uživatele.
  • Celý dokument se přepisuje při každé změně. V pořádku pro 30‑stránkovou smlouvu, špatně pro archiv o 2 000 stránkách.
  • Neexistuje žádná autentizace. Každý volající ve vzorku je „Reviewer“.

Spusťte to

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

Nebo v kontejneru, s --network none, pokud chcete sledovat, jak to funguje bez jakéhokoli odchozího provozu:

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

Krok‑za‑krokem verze je v dokumentaci:
Vytvořte uživatelské rozhraní pro anotace pro vaši webovou aplikaci Pokud už vkládáte JavaScript PDF prohlížeč, ponechte jej pro zobrazování a použijte tyto koncové body jen pro úložiště — žádná z geometrických pravidel se nezmění.