Анотації

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

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

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

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

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

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

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>

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

html
<script>
    let annBar = null;
    let currentToken = '';

    const objViewer = $('#div_ctlDoc').docViewer({
        BasePath: '/',
        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 виключає скрипт Ribbon, тому серверний if захищає незахищений виклик doconutAnnotationBar(...) від поломки сторінки.

Збереження з Ribbon надсилає дані через проміжне ПЗ (AnnSave), яке зберігає їх у сесії документа по сторінках. Завантаження (AnnLoad) відбувається автоматично, коли сторінка з анотаціями відображається. Чотири зворотні виклики onAnn* підтримують синхронізацію Ribbon з життєвим циклом переглядача.

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

javascript
annBar.open();
annBar.close();

Публічний API Ribbon:

МетодПризначення
attach(objViewer)Підключити Ribbon до ініціалізованого переглядача; потрібно один раз
open() / close()Вступити в режим редагування анотацій або вийти з нього
reset()Повернути Ribbon у закрите, не редагувальне стан
isOpen() / annotating()Прочитати стан Ribbon / стан редагування анотацій у переглядачі
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 і
    // renderer записує їх у експорт зображень/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/скрипту анотацій
Зворотний виклик збереження повідомляє про помилкуТермін дії токена/сеансу закінчився та middleware BasePath
ctlDoc_Created (або інша функція події) ніколи не виконуєтьсяНазва функції: ідентифікатор переглядача + _ + подія, як глобальна функція
Анотації C# не відображаютьсяНумерація сторінок починається з 1, і дані були завантажені в активний токен
Анотація зображення відображається на екрані, але не в експортіХост зображення має приватну або loopback адресу — дивіться вище
Повторно відкритий документ не містить анотаційЗбережіть XML/дані поза сеансом переглядача, потім завантажте їх у новий токен

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