GroupDocs.Annotation не зависит от UI. Он читает и записывает разметку внутри документов и ничего не рисует на экране. Для серверной библиотеки это правильное разделение — и у всех, кто её использует, возникает один вопрос: как человек действительно рисует аннотацию?
Обычные ответы тяжёлые: внедрить коммерческий просмотрщик или использовать демо‑пример на Angular и затем пытаться его расширять. Есть более лёгкое решение. Изображения страниц, canvas и шесть конечных точек — без компонента просмотрщика, без фронтенд‑фреймворка, без шага сборки, без CDN. Оно также работает без какого‑либо исходящего сетевого доступа, что теперь важнее, чем было раньше.
Пример доступен на GitHub:
browser-annotation-ui-net — dotnet run и перетащите коробку на страницу.
Идея в одном абзаце
Отрендерить каждую страницу один раз как PNG без аннотаций и закешировать её. Отправить список аннотаций в браузер как данные. Canvas рисует разметку поверх изображения. Добавление комментария тогда представляет собой небольшую запись в документ плюс перезагрузку списка — без повторного рендеринга страницы — и разметка остаётся выбираемой, кликабельной и отвечаемой, а не запечённой в картинку.
Конечные точки
| Метод | Маршрут | Назначение |
|---|---|---|
GET |
/api/documents/{name}/info |
количество страниц и размер каждой страницы в пунктах |
GET |
/api/documents/{name}/pages/{n}/image |
PNG страницы n |
GET |
/api/documents/{name}/annotations |
каждая аннотация как один прямоугольник в единицах страницы |
POST |
/api/documents/{name}/annotations |
добавить одну |
PUT |
/api/documents/{name}/annotations/{id} |
изменить сообщение или добавить ответ |
DELETE |
/api/documents/{name}/annotations/{id} |
удалить одну |
Каждая запись возвращает полный список, поэтому браузеру никогда не придётся разбираться, что сейчас хранит сервер.
Рендеринг
PreviewOptions previewOptions = new(page => File.Create(CachePath(name, page)))
{
PreviewFormat = PreviewFormats.PNG,
PageNumbers = new[] { pageNumber }, // 1-based
RenderAnnotations = false, // canvas рисует разметку
Resolution = 144
};
annotator.Document.GeneratePreview(previewOptions);
Сравнивайте метку времени кешированного изображения с меткой времени документа и пере‑рендерьте только когда документ действительно изменился.
Пиксели на входе, единицы страницы на выходе
Canvas хранит свой прямоугольник в пикселях изображения и отправляет размер изображения, на котором он рисовал — без коэффициента масштабирования:
body: JSON.stringify({
page: currentPage,
x, y, width, height,
imageWidth: img.clientWidth,
imageHeight: img.clientHeight,
message: window.prompt('Comment'),
user: 'Reviewer'
})
Это решение сохраняет корректность UI, когда меняется разрешение превью, когда CSS масштабирует изображение или когда кто‑то открывает его на телефоне. Сервер выполняет арифметику:
double scaleX = page.Width / request.ImageWidth;
double scaleY = page.Height / request.ImageHeight;
annotator.Add(new AreaAnnotation
{
PageNumber = page.PageNumber - 1, // PageInfo 1‑based, аннотации 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 измеряется от левого верхнего угла страницы — в том же направлении, в котором измеряет браузер — поэтому нарисованный прямоугольник отображается с масштабом и без отражения.
Отправка одной формы прямоугольника в браузер
Текстовая разметка не использует эту же точку отсчёта. HighlightAnnotation.Points и связанные с ней элементы измеряются от нижнего левого угла. Преобразуйте их на сервере, чтобы фронтенд видел только прямоугольники с левым верхним углом:
x = minX;
y = page.Height - maxY; // переворачиваем к левому верхнему
width = maxX - minX;
height = maxY - minY;
Сделайте так, и выделение, добавленное в Word, Acrobat или через automated review pass, появится в правильном месте в вашем UI, не требуя от JavaScript знать что‑либо о геометрии PDF.
Запись в файлы‑заменители
Аннотатор держит исходный файл открытым и не может сохранить изменения прямо в него:
using (Annotator annotator = new Annotator(path))
{
annotator.Add(annotation);
annotator.Save(path + ".tmp");
}
File.Move(path + ".tmp", path, overwrite: true);
InvalidatePreviewCache(name);
Возьмите блокировку на документ вокруг всей последовательности. Два запроса, которые одновременно читают, изменяют и переписывают один и тот же файл, приведут к потере одного из изменений.
Что этот дизайн не решает
Стоит сказать откровенно, потому что это определяет, сможете ли вы использовать его «как есть»:
- Идентификаторы аннотаций меняются после записи. Они присваиваются во время чтения документа, а не хранятся в нём. UI, который перезагружает список после каждого изменения, будет работать. В многопользовательской системе следует хранить аннотации в отдельной таблице и использовать импорт/экспорт для перемещения их в файл и из файла — так же вы получаете журнал аудита и видимость per‑user.
- Весь документ переписывается при каждом изменении. Подходит для 30‑страничного контракта, но не для архива в 2 000 страниц.
- Отсутствует аутентификация. Каждый вызывающий в примере — «Reviewer».
Запуск
git clone https://github.com/groupdocs-annotation/browser-annotation-ui-net.git
cd browser-annotation-ui-net
dotnet run --project src/AnnotationUi
Или в контейнере, с --network none, если хотите увидеть работу без какого‑либо исходящего трафика:
docker build -t annotation-ui .
docker run --rm -p 8080:8080 annotation-ui
Пошаговая версия находится в документации:
Создайте пользовательский интерфейс аннотаций для вашего веб‑приложения.
Если вы уже внедрили JavaScript‑просмотрщик PDF, оставьте его для отображения и используйте только эти конечные точки для хранения — правила геометрии не меняются.