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í.