Анотації

Додайте підтримку анотацій у переглядач

Анотації в Doconut працюють у два напрямки: користувачі малюють їх у віджеті браузера, а сервер зберігає їх по сторінках, або ваш код створює їх програмно і завантажує у відкриту сесію. У будь‑якому випадку вони відображаються на сторінках і можуть бути вбудовані у експорти PDF/PNG.

Підтримка анотацій обмежена можливістю ліцензії Annotation (надається автоматично при активній тимчасовій ліцензії).

Увімкнути інтерфейс анотацій

Анотація — це модуль Переглядача, а не окрема панель інструментів. Повна сторінка повинна містити ресурси Переглядача, панель інструментів Переглядача, монтування Переглядача та ініціалізований objViewer; після цього стрічка Анотації монтується і приєднується до того ж екземпляра.

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

html
@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  // вбудована стрічка анотацій
}))

Залиште повну композицію Переглядача видимою в розмітці:

html
<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, а потім створюйте стрічку лише коли сервер підтвердить, що Анотація ліцензовано:

html
<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* підтримують синхронізацію стрічки з життєвим циклом Переглядача.

Відкривайте та закривайте її з будь-якої панелі інструментів Переглядача, що належить хосту:

javascript
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):

csharp
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).

Експорт з вбудованими анотаціями

csharp
// 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‑адресу та повідомлення про помилку червоним кольором там, де має бути зображення.

Робочий процес збереження

  1. Відкрийте документ і отримайте його токен.
  2. Завантажте раніше збережений XML або закодовані дані в цей токен.
  3. Дайте віджету прочитати та відредагувати анотації сесії.
  4. Отримайте XML за допомогою GetAnnotationXML(token), коли ваш застосунок вирішить зберегти.
  5. Експортуйте PDF/PNG, коли потрібен сплощений результат.
  6. Закрийте сесію документа.

Не використовуйте непрозорий токен переглядача як постійний ідентифікатор анотації. Пов’язуйте збережені дані анотацій зі своїми ідентифікаторами документа та його версії.

Примітки щодо безпеки та рендерингу

  • Запити анотацій використовують ту ж безпеку сесії/токену, що й запити сторінок.
  • Перевіряйте та контролюйте будь‑яку URL‑адресу зображення, надану користувачем, щоб уникнути підробки запитів на стороні сервера.
  • Експорти застосовують ті ж рішення щодо ліцензії/власного водяного знака, що й рендеринг сторінки на екрані.
  • Великі довільні навантаження та експорт у високій роздільній здатності збільшують використання пам’яті; тестуйте реалістичні документи та значення масштабування.

Усунення неполадок

СимптомПеревірка
Рядок анотацій відсутнійможливість Annotation та чотири прапорці CSS/скриптів анотацій
Зворотний виклик збереження повідомляє про помилкузакінчення терміну дії токену/сесії та проміжне ПЗ BasePath
ctlDoc_Created (або інша функція події) ніколи не виконуєтьсяназва функції: ідентифікатор переглядача + _ + подія, як глобальна функція
Анотації C# не відображаютьсянумерація сторінок починається з 1, і дані були завантажені в активний токен
Анотація зображення відображається на екрані, але не в експортіхост зображення має приватну або loopback‑адресу — дивіться вище
Після повторного відкриття документ не містить анотаційзбережіть XML/дані поза сесією переглядача, потім завантажте їх у новий токен

Чи була ця сторінка корисною?