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, оставьте его для отображения и используйте только эти конечные точки для хранения — правила геометрии не меняются.