Анотації

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

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

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

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

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

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

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

Залиште повний склад Viewer видимим у розмітці:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Елементи керування переглядачем, включаючи кнопку, що відкриває Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

Пакет Annotation генерує DOM стрічки всередині annBarMount; вам не потрібно копіювати його кнопки чи розмітку діалогового вікна. Спочатку ініціалізуйте docViewer, а потім створюйте стрічку лише коли сервер підтвердить, що Annotation ліцензовано:

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

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

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; елементи керування без налаштованої кінцевої точки залишаються прихованими.

Для послідовності запуску комбінованих Viewer, Search та Annotation дивіться Швидкий старт.

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

ЧленПризначення
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/дані поза сеансом переглядача, потім завантажте їх у новий токен

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