Анотації
Додайте підтримку анотацій до переглядача
Анотації в Doconut працюють у двох напрямках: користувачі малюють їх у віджеті браузера, а сервер зберігає їх по сторінках, або ваш код створює їх і завантажує в відкриту сесію. У будь‑якому випадку вони відображаються на сторінках і можуть бути вбудовані у PDF або PNG експорт.
Підтримка анотацій обмежена можливістю ліцензії Annotation (надається автоматично при активній тимчасовій ліцензії).
Увімкнути інтерфейс анотацій
Анотація — це модуль Viewer, а не окрема панель інструментів. Сторінка повинна включати ресурси Viewer, панель інструментів Viewer, монтування Viewer та ініціалізований objViewer; потім стрічка Annotation монтується і приєднується до того ж екземпляру.
Виведіть файли анотацій разом з файлами переглядача. Вони обмежені ліцензією, тому їхні теги з'являються лише коли можливість надана. У MVC 5 створюйте теги у контролері (у представленнях немає @inject):
public class ViewerController : Controller
{
public ActionResult Index()
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
{
IncludeViewerCss = true,
IncludeAnnotationCss = true // jquery-ui.min.css + annotationBar.css
});
ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeViewerScripts = true,
IncludeAnnotationScripts = true, // jquery-ui, raphael.js, annotation.js
IncludeAnnotationBar = true // вбудована стрічка анотації
});
ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
return View();
}
}Зберігайте повний склад Viewer у розмітці:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Елементи керування переглядачем, включаючи кнопку, що відкриває Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>Файли Annotation генерують стрічку всередині annBarMount; ви не копіюєте її кнопки чи діалогові вікна. Спочатку ініціалізуйте docViewer, а потім створюйте стрічку лише коли сервер підтвердить, що Annotation ліцензовано:
@Html.Raw(ViewBag.ViewerCss)
@Html.Raw(ViewBag.ViewerScripts)
<script>
var annBar = null;
var currentToken = '';
var objViewer = $('#div_ctlDoc').docViewer({
BasePath: '/',
ResPath: 'doconut-res/images',
onAnnLoaded: function () { if (annBar) annBar.handleAnnLoaded(); },
onAnnSaved: function () { if (annBar) annBar.handleAnnSaved(); },
onAnnSaveError: function () { if (annBar) annBar.handleAnnSaveError(); },
onAnnClosed: function () { if (annBar) annBar.handleAnnClosed(); },
onError: function (message) { console.error('Viewer error:', message); }
});
@if ((bool)ViewBag.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: function () { return { token: currentToken }; },
onLayout: function () { requestAnimationFrame(function () { objViewer.Refit(); }); }
});
annBar.attach(objViewer);
</text>
}
</script>Без цієї можливості ReferenceScripts пропускає скрипт стрічки, тому серверний if захищає незахищений виклик doconutAnnotationBar(...) від поломки сторінки. У Web Forms напишіть таку ж охорону як <% if (IsAnnotationEnabled) { %> … <% } %>.
Збереження зі стрічки надсилає дані до DocImage.axd (AnnSave), які зберігаються у сесії документа по сторінках. Завантаження (AnnLoad) відбувається автоматично, коли сторінка з анотаціями відображається.
Відкривайте та закривайте стрічку зі своєї панелі інструментів за допомогою 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; елементи керування без налаштованої кінцевої точки залишаються прихованими.
Два типи зворотних викликів, підключені двома способами
Код анотацій використовує два стилі зворотних викликів, і кожен безшумно не працює, коли підключений іншим способом:
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):
// POST /Annotations/LoadSample?token=...
[HttpPost]
public ActionResult LoadSample(string token)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<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));
// Завантажити в сесію - переглядач отримує їх, а рендерер вбудовує їх у
// експорти image/PDF.
viewer.LoadAnnotationData(token, manager);
return new HttpStatusCodeResult(200);
}Типи анотацій
Усі типи знаходяться в 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) | Закодовані дані анотації — конверт, який споживає віджет |
GetAnnotationXml() | XML-форма |
Viewer віддзеркалює операції завантаження та читання проти сесії: LoadAnnotationData(token, manager) або LoadAnnotationData(token, encodedData), LoadAnnotationXML(token, xml), і GetAnnotationXML(token).
Експорт з вбудованими анотаціями
// PDF усіх сторінок з анотаціями, відмальованими на них
public async Task<ActionResult> ExportPdf(string token)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
return File(pdf, "application/pdf", "export.pdf");
}
// Або ZIP з PNG‑файлами по сторінках
public async Task<ActionResult> ExportPngZip(string token)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
return 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 (або інша функція події) ніколи не виконується | Назва функції: viewer id + _ + event, як глобальна функція |
| Анотації C# не відображаються | Нумерація сторінок починається з 1, і дані були завантажені в активний токен |
| Анотація зображення відображається на екрані, але не в експорті | Хост зображення має приватну або loopback‑адресу — дивіться вище |
| Повторно відкритий документ не містить анотацій | Збережіть XML або дані поза сесією переглядача, потім завантажте їх у новий токен |
Чи була ця сторінка корисною?