Аннотации

Добавьте поддержку аннотаций в просмотрщик

Аннотации в 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">
    <!-- Элементы управления Viewer, включая кнопку, открывающую 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 являются глобальными функциями, найденными по имени: к событию добавляется префикс id просмотрщика. Для просмотрщика в #div_ctlDoc id равен 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 exports.
    viewer.LoadAnnotationData(token, manager);
    return new HttpStatusCodeResult(200);
}

Типы аннотаций

Все типы находятся в Doconut.Annotations и наследуются от BaseAnnotation (номер страницы плюс ограничивающий Rectangle):

TypeNotes
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

MemberPurpose
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");
}

Экспорты используют тот же механизм «burner», что и отрисовка на экране, а также ту же лицензию и решение о пользовательском водяном знаке.

Аннотации изображений на интранет‑хосте экспортируются как «Изображение заблокировано»

Просмотрщик и экспорт получают изображение ImageAnnotation's из разных мест:

КонтекстКто загружает изображениеНа интранет‑хосте или в среде разработки
Просмотрщик в браузереБраузер пользователяИзображение отображается
ExportAnnotationsToPdfAsync / …PngZipAsyncСерверКрасный заполнитель «Image blocked»

Когда сервер получает изображение для встраивания, он отклоняет адреса, указывающие обратно в частные сети: 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 или данные вне сеанса просмотрщика, затем загрузите их в новый токен

Была ли эта страница полезной?