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