Анотації

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

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

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

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

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

Виведіть файли анотацій разом з файлами переглядача. Вони обмежені ліцензією, тому їхні теги з'являються лише коли можливість надана. У MVC 5 створюйте теги у контролері (у представленнях немає @inject):

csharp
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 у розмітці:

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 генерують стрічку всередині annBarMount; ви не копіюєте її кнопки чи діалогові вікна. Спочатку ініціалізуйте docViewer, а потім створюйте стрічку лише коли сервер підтвердить, що Annotation ліцензовано:

html
@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):

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

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

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

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

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

Не використовуйте токен переглядача як постійний ідентифікатор анотації — він зникає разом із сесією, а перезапуск пулу застосунків завершує кожну сесію на окремому сервері. Зберігайте дані анотацій у власних ідентифікаторах документів та їх версій.

Примітки щодо безпеки та відображення

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

Усунення проблем

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

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