GroupDocs.Annotation jest niezależny od interfejsu użytkownika. Odczytuje i zapisuje znaczniki w dokumentach i nie rysuje nic na ekranie. Dla biblioteki serwerowej to właściwy podział — i pozostawia jedno pytanie dla wszystkich, którzy ją przyjmują: jak osoba faktycznie rysuje adnotację?
Zwykłe odpowiedzi są ciężkie: osadzenie komercyjnego przeglądarki, lub przyjęcie demo Angular i próba jego rozszerzenia. Jest lżejsza opcja. Obrazy stron, płótno i sześć punktów końcowych — brak komponentu przeglądarki, brak frameworka front‑end, brak kroku budowania, brak CDN. Działa również bez żadnego wychodzącego dostępu do sieci, co ma teraz większe znaczenie niż kiedyś.
Przykład znajduje się na GitHubie: browser-annotation-ui-net — dotnet run i przeciągnij prostokąt na stronie.
Pomysł w jednym akapicie
Renderuj każdą stronę raz jako PNG bez adnotacji i zapisz ją w pamięci podręcznej. Wyślij listę adnotacji do przeglądarki jako dane. Płótno rysuje znaczniki na obrazie. Dodanie komentarza to wtedy mały zapis do dokumentu plus odświeżenie listy — nie ponowne renderowanie strony — a znaczniki pozostają wybieralne, klikalne i możliwe do odpowiedzi, zamiast być wtopione w obraz.
Punkty końcowe
| Metoda | Ścieżka | Cel |
|---|---|---|
GET |
/api/documents/{name}/info |
liczba stron i rozmiar każdej strony, w punktach |
GET |
/api/documents/{name}/pages/{n}/image |
PNG strony n |
GET |
/api/documents/{name}/annotations |
każda adnotacja jako jeden prostokąt w jednostkach strony |
POST |
/api/documents/{name}/annotations |
dodaj jedną |
PUT |
/api/documents/{name}/annotations/{id} |
zmień wiadomość lub dodaj odpowiedź |
DELETE |
/api/documents/{name}/annotations/{id} |
usuń jedną |
Każdy zapis zwraca pełną listę, więc przeglądarka nigdy nie musi rozważać, co serwer aktualnie przechowuje.
Renderowanie
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);
Porównaj znacznik czasu zbuforowanego obrazu z dokumentem i renderuj ponownie tylko wtedy, gdy dokument faktycznie się zmienił.
Piksele w, jednostki strony na wyjściu
Płótno przechowuje swój prostokąt w pikselach obrazu i wysyła rozmiar obrazu, na którym rysuje — nie współczynnik skali:
body: JSON.stringify({
page: currentPage,
x, y, width, height,
imageWidth: img.clientWidth,
imageHeight: img.clientHeight,
message: window.prompt('Comment'),
user: 'Reviewer'
})
Ta jedna decyzja jest tym, co utrzymuje UI poprawnym, gdy zmienia się rozdzielczość podglądu, gdy CSS skaluje obraz lub gdy ktoś otwiera go na telefonie. Serwer wykonuje obliczenia:
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 jest mierzony od lewego górnego rogu strony — w tym samym kierunku, w jakim mierzy przeglądarka — więc narysowany prostokąt mapuje się przy skali bez odwrócenia.
Wyślij jedną formę prostokąta do przeglądarki
Znaczniki tekstowe nie dzielą tego pochodzenia. HighlightAnnotation.Points i ich odpowiedniki są mierzone od lewego dolnego rogu. Konwertuj na serwerze, aby front‑end widział zawsze prostokąty od lewego górnego rogu:
x = minX;
y = page.Height - maxY; // flip to top-left
width = maxX - minX;
height = maxY - minY;
Zrób to, a podświetlenie dodane w Wordzie, w Acrobatcie lub przez automatyczną recenzję pojawi się we właściwym miejscu w Twoim UI, bez tego, aby JavaScript wiedział cokolwiek o geometrii PDF.
Zapisuje pliki wymiany
Annotator trzyma otwarty źródłowy plik i nie może zapisać nad plikiem, który odczytuje:
using (Annotator annotator = new Annotator(path))
{
annotator.Add(annotation);
annotator.Save(path + ".tmp");
}
File.Move(path + ".tmp", path, overwrite: true);
InvalidatePreviewCache(name);
Zastosuj blokadę per dokument wokół całej sekwencji. Dwa żądania, które jednocześnie odczytują, zmieniają i przepisują ten sam plik, utracą jedną ze zmian.
Co ten projekt nie rozwiązuje
Warto to jasno powiedzieć, ponieważ decyduje, czy możesz go wypuścić w takiej formie:
- Identyfikatory adnotacji zmieniają się po zapisie. Są przydzielane podczas odczytu dokumentu, nie są w nim przechowywane. UI, które odświeża listę po każdej zmianie, jest w porządku. System wieloużytkownikowy powinien przechowywać adnotacje w własnej tabeli i używać importu oraz eksportu, aby przenosić je do i z pliku — co jest także sposobem na uzyskanie ścieżki audytu i widoczności per użytkownik.
- Cały dokument jest przepisywany przy każdej zmianie. W porządku dla 30‑stronicowego kontraktu, niewłaściwe dla archiwum o 2 000 stronach.
- Brak uwierzytelniania. Każdy wywołujący w przykładzie jest „Reviewer”.
Uruchomienie
git clone https://github.com/groupdocs-annotation/browser-annotation-ui-net.git
cd browser-annotation-ui-net
dotnet run --project src/AnnotationUi
Lub w kontenerze, z --network none, jeśli chcesz obserwować działanie bez żadnego wychodzącego ruchu:
docker build -t annotation-ui .
docker run --rm -p 8080:8080 annotation-ui
Wersja krok po kroku znajduje się w dokumentacji: Build an annotation UI for your web app. Jeśli już osadzasz przeglądarkę PDF w JavaScript, zachowaj ją do wyświetlania i używaj tych punktów końcowych wyłącznie do przechowywania — żadne zasady geometrii się nie zmieniają.