Анотації
Додайте підтримку анотацій у переглядач
Анотації в Doconut працюють у два напрямки: користувачі малюють їх у віджеті браузера, а сервер зберігає їх по сторінках, або ваш код створює їх програмно і завантажує у відкриту сесію. У будь‑якому випадку вони відображаються на сторінках і можуть бути вбудовані у експорти PDF/PNG.
Підтримка анотацій обмежена можливістю ліцензії Annotation (надається автоматично при активній тимчасовій ліцензії).
Увімкнути інтерфейс анотацій
Анотація — це модуль Переглядача, а не окрема панель інструментів. Повна сторінка повинна містити ресурси Переглядача, панель інструментів Переглядача, монтування Переглядача та ініціалізований objViewer; після цього стрічка Анотації монтується і приєднується до того ж екземпляра.
Виводьте пакети анотацій разом з пакетами Переглядача — вони обмежені ліцензією, тому теги з’являються лише коли можливість доступна:
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeViewerCss = true,
IncludeAnnotationCss = true // jquery-ui.min.css + annotationBar.css
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeViewerScripts = true,
IncludeAnnotationScripts = true, // jquery-ui, raphael.js, annotation.js
IncludeAnnotationBar = true // вбудована стрічка анотацій
}))Залиште повну композицію Переглядача видимою в розмітці:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Елементи управління переглядачем, включаючи кнопку, що відкриває Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>Пакет Анотації генерує DOM стрічки всередині annBarMount; вам не потрібно копіювати його кнопки або розмітку діалогових вікон. Спочатку ініціалізуйте docViewer, а потім створюйте стрічку лише коли сервер підтвердить, що Анотація ліцензовано:
<script>
let annBar = null;
let currentToken = '';
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: 'doconut',
ResPath: 'doconut-res/images',
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: (message) => console.error('Viewer error:', message)
});
@if (Viewer.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token: currentToken }),
onStatus: (message) => console.log(message),
onToast: (message, type) => console.log(type, message),
onLayout: () => requestAnimationFrame(() => objViewer.Refit())
});
annBar.attach(objViewer);
</text>
}
</script>Без цієї можливості ReferenceScripts виключає скрипт стрічки, тому серверний if захищає незахищений виклик doconutAnnotationBar(...) від поломки сторінки.
Збереження зі стрічки надсилає дані через проміжне ПЗ (AnnSave), яке зберігає їх у сесії документа по сторінках. Завантаження (AnnLoad) відбувається автоматично, коли рендериться сторінка з анотаціями. Чотири зворотні виклики onAnn* підтримують синхронізацію стрічки з життєвим циклом Переглядача.
Відкривайте та закривайте її з будь-якої панелі інструментів Переглядача, що належить хосту:
annBar.open();
annBar.close();Публічний API стрічки:
| Метод | Призначення |
|---|---|
attach(objViewer) | Підключити стрічку до ініціалізованого Переглядача; потрібно один раз |
open() / close() | Увійти в режим редагування анотацій або вийти з нього |
reset() | Повернути стрічку у закрите, не редагувальне стан |
isOpen() / annotating() | Прочитати стан стрічки / стан редагування анотацій у Переглядачі |
reopenEditable() | Перезавантажити анотації поточної сторінки як редаговані об’єкти |
updateActionState() | Оновити доступність елементів керування збереженням/видаленням після змін хосту |
headerSlot() | Отримати необов’язковий слот розширення заголовка для елементів, що належать хосту |
onStatus, onToast, onLayout, onEditStart та onEditEnd — це необов’язкові зворотні виклики хоста. Об’єкт endpoints може додатково надавати exportPdf, exportPng, imageUpload та imageList; елементи без налаштованої кінцевої точки залишаються прихованими.
Для послідовності запуску комбінованих Переглядач, Search та Анотація дивіться Швидкий старт.
Пакет анотацій додає інструменти авторингу в браузері, проте дані все ще належать серверній сесії документа, ідентифікованій токеном. Повторне відкриття джерела створює нову сесію; збережіть XML або закодований конверт анотацій у вашому застосунку, якщо анотації мають залишатися після завершення сесії.
Два типи зворотних викликів, підключені двома способами
Код анотацій використовує два стилі зворотних викликів, і кожен без повідомлення про помилку не працює, коли підключений іншим способом:
onAnnLoaded,onAnnSaved,onAnnSaveError,onAnnClosedє опціямиdocViewer({...}), як і кожен зворотний виклик переглядача.Created,Changed,Deleted, іPropertiesє глобальними функціями, знайденими за назвою: ідентифікатор переглядача додається як префікс до події. Для переглядача в#div_ctlDocідентифікатор —ctlDoc, тому функції —ctlDoc_Created,ctlDoc_Changed,ctlDoc_Deleted, іctlDoc_Properties. Помилково написана або перейменована функція просто ніколи не викликається.
SaveAnnotations() не повертає, чи було збережено: результат надходить через onAnnSaved або onAnnSaveError. Код, який читає його повернене значення, ніколи не скидає прапорець «незбережені зміни».
Створення анотацій у C#
Отримайте менеджер, прив’язаний до відкритої сесії, додайте анотації та завантажте їх (за допомогою using Doconut.Annotations; для типів і using System.Drawing; для Rectangle/Color):
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
// Прив’язано до розмірів сторінки відкритої сесії
var manager = viewer.GetAnnotationManager(token);
var pageCount = viewer.GetPageCount(token);
// Один штамп на сторінку
for (int page = 1; page <= pageCount; page++)
{
manager.Add(new StampAnnotation(page, new Rectangle(30, 20, 240, 90),
$"PAGE {page}", 28, 4, Color.Maroon)
{
Opacity = 60,
Rotate = -8
});
}
manager.Add(new NoteAnnotation(1, new Rectangle(420, 150, 220, 120),
"Loaded from C# code.", Color.FromArgb(255, 255, 255, 170), 14));
// Завантажити у сесію — віджет отримує їх через AnnLoad і
// renderer вбудовує їх у image/PDF експорти.
viewer.LoadAnnotationData(token, manager);
return Results.Ok();
});Типи анотацій
Усі типи розташовані в Doconut.Annotations і успадковуються від BaseAnnotation (номер сторінки + обмежувальний Rectangle):
| Тип | Примітки |
|---|---|
StampAnnotation | Текстовий штамп з розміром шрифту, рамкою, кольором; підтримує Opacity, Rotate |
NoteAnnotation | Нотатка‑стікер з текстом, кольором фону, розміром шрифту, TitleColor |
RectangleAnnotation | Кольори рамки та заповнення, Title/ShowTitle |
CircleAnnotation | Рамка + заповнення, ShowBorder |
EllipseAnnotation | Рамка + заповнення, ShowBorder |
TriangleAnnotation | Колір рамки, BackColor, ShowBorder |
LineAnnotation | Пряма лінія з шириною та кольором |
ArrowAnnotation | Лінія зі стрілкою; налаштовуваний Direction (тип ArrowDirection, напрямки компаса, за замовчуванням E) |
FreehandAnnotation | Вільний штрих з закодованих точок FreehandData |
ImageAnnotation | Зображення за URL. Відносний URL розв’язується відносно хоста запиту під час додавання анотації; сервер завантажує зображення лише під час «запікання» — дивіться примітку про експорт нижче |
API AnnotationManager
| Член | Призначення |
|---|---|
Add(BaseAnnotation) | Додати анотацію в чергу |
GetAnnotations() / GetAnnotations(int page) | Перевірити, що містить менеджер |
ClearAnnotations() / ClearAnnotations(int page) | Видалити всі / по сторінці |
GetAnnotationData() / GetAnnotationData(int page) | Закодований рядок даних анотації — Base64 обгортка (те, що споживає віджет) |
GetAnnotationXml() | XML‑форма |
Viewer відображає операції завантаження/читання щодо сесії: LoadAnnotationData(token, manager) або LoadAnnotationData(token, encodedData) (Base64 обгортка від GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).
Експорт з вбудованими анотаціями
// PDF усіх сторінок з анотаціями, відображеними на них
app.MapGet("/api/annotations/export-pdf", async (string token, Viewer viewer) =>
{
byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100);
return Results.File(pdf, "application/pdf", "export.pdf");
});
// Або ZIP з PNG‑файлами по кожній сторінці
app.MapGet("/api/annotations/export-png-zip", async (string token, Viewer viewer) =>
{
byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100);
return Results.File(zip, "application/zip", "annotations-png.zip");
});Експорти використовують той самий процес «запікання», що й відображення на екрані, тому те, що бачать користувачі, відповідає вмісту файлу — за винятком зображень‑анотацій, описаних далі.
Анотації зображень на інтра‑нет хості експортуються як «Зображення заблоковано»
Переглядач і експорт отримують зображення ImageAnnotation з різних джерел:
| Контекст | Хто завантажує зображення | На інтра‑нет або розробницькому хості |
|---|---|---|
| Переглядач у браузері | Браузер користувача | Зображення відображається |
ExportAnnotationsToPdfAsync / …PngZipAsync | Сервер | Червоний заповнювач «Зображення заблоковано» |
Коли сервер отримує зображення для вбудовування, він відхиляє адреси, що повертаються у приватні мережі: loopback (localhost, 127.0.0.1), 0.0.0.0, link‑local (169.254.x.x), приватні діапазони 10.x, 172.16–31.x і 192.168.x, carrier‑grade NAT (100.64.0.0/10) та IPv6 link‑local і unique‑local адреси. Це захищає сервер від використання для доступу до внутрішніх систем через спеціально сформовану URL‑адресу зображення, і вимкнути цей захист неможливо.
Відносна URL‑адреса зображення розв’язується відносно хоста поточного запиту, тому на localhost, на інтра‑нет сервері або на будь‑якому сайті, доступному через приватну адресу, зображення відображається у переглядачі, а експорт містить заповнювач. Це працює захист, а не збій рендерингу. Якщо в експорті має бути саме зображення, розмістіть його на хості з публічною адресою та використовуйте абсолютну URL‑адресу. Ім’я хоста, яке не може бути розв’язане, відхиляється так само; будь‑яка інша помилка завантаження відображає URL‑адресу та повідомлення про помилку червоним кольором там, де має бути зображення.
Робочий процес збереження
- Відкрийте документ і отримайте його токен.
- Завантажте раніше збережений XML або закодовані дані в цей токен.
- Дайте віджету прочитати та відредагувати анотації сесії.
- Отримайте XML за допомогою
GetAnnotationXML(token), коли ваш застосунок вирішить зберегти. - Експортуйте PDF/PNG, коли потрібен сплощений результат.
- Закрийте сесію документа.
Не використовуйте непрозорий токен переглядача як постійний ідентифікатор анотації. Пов’язуйте збережені дані анотацій зі своїми ідентифікаторами документа та його версії.
Примітки щодо безпеки та рендерингу
- Запити анотацій використовують ту ж безпеку сесії/токену, що й запити сторінок.
- Перевіряйте та контролюйте будь‑яку URL‑адресу зображення, надану користувачем, щоб уникнути підробки запитів на стороні сервера.
- Експорти застосовують ті ж рішення щодо ліцензії/власного водяного знака, що й рендеринг сторінки на екрані.
- Великі довільні навантаження та експорт у високій роздільній здатності збільшують використання пам’яті; тестуйте реалістичні документи та значення масштабування.
Усунення неполадок
| Симптом | Перевірка |
|---|---|
| Рядок анотацій відсутній | можливість Annotation та чотири прапорці CSS/скриптів анотацій |
| Зворотний виклик збереження повідомляє про помилку | закінчення терміну дії токену/сесії та проміжне ПЗ BasePath |
ctlDoc_Created (або інша функція події) ніколи не виконується | назва функції: ідентифікатор переглядача + _ + подія, як глобальна функція |
| Анотації C# не відображаються | нумерація сторінок починається з 1, і дані були завантажені в активний токен |
| Анотація зображення відображається на екрані, але не в експорті | хост зображення має приватну або loopback‑адресу — дивіться вище |
| Після повторного відкриття документ не містить анотацій | збережіть XML/дані поза сесією переглядача, потім завантажте їх у новий токен |
Чи була ця сторінка корисною?