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,            // the canvas draws the markup
    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 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 вимірюється від верхнього лівого кута сторінки — у тому ж напрямку, у якому вимірює браузер — тому намальований прямокутник відображається з масштабом і без перевертання.

Надішліть одну форму прямокутника у браузер

Текстова розмітка не має цього походження. HighlightAnnotation.Points та його родичі вимірюються від нижнього лівого кута. Перетворюйте на сервері, щоб фронтенд бачив лише прямокутники у верхньому лівому куті:

x = minX;
y = page.Height - maxY;      // flip to top-left
width = maxX - minX;
height = maxY - minY;

Зробіть це, і підсвічування, додане у Word, у Acrobat або за допомогою автоматизованого проходу ревізії, з’явиться у правильному місці вашого UI, не вимагаючи від JavaScript знань про геометрію PDF.

Записи створюють swap‑файли

Annotator тримає джерело відкритим і не може зберегти поверх файлу, який читає:

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

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

Візьміть блокування на рівні документа навколо всієї послідовності. Два запити, які одночасно читають, змінюють і переписують один і той же файл, втратять одну зі змін.

Що цей дизайн не вирішує

Варто сказати це відверто, бо це визначає, чи можете ви випускати його в такому вигляді:

  • Ідентифікатори анотацій змінюються після запису. Вони присвоюються під час читання документа, а не зберігаються в ньому. UI, який перезавантажує список після кожної зміни, підходить. Багато користувачний система повинна зберігати анотації у власній таблиці та використовувати імпорт і експорт для переміщення їх у файл і з файлу — це також спосіб отримати журнал аудиту та видимість для кожного користувача.
  • Весь документ переписується при кожній зміні. Підходить для 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

Покрокова версія знаходиться в документації: Build an annotation UI for your web app. Якщо ви вже вбудували JavaScript PDF переглядач, залиште його для відображення і використовуйте ці кінцеві точки лише для зберігання — жодне з правил геометрії не змінюється.