Аннотации
Добавьте поддержку аннотаций в просмотрщик
Аннотации в Doconut работают в двух направлениях: пользователи рисуют их в браузерном виджете, а сервер сохраняет их по страницам, либо ваш код создает их программно и загружает в открытую сессию. В любом случае они отображаются на страницах и могут быть включены в экспорт PDF/PNG.
Поддержка аннотаций ограничена возможностью лицензии Annotation (предоставляется автоматически при активной временной лицензии).
Включить пользовательский интерфейс аннотаций
Аннотация — это модуль Viewer, а не отдельная панель инструментов. Полная страница должна включать ресурсы Viewer, панель инструментов Viewer, монтирование Viewer и инициализированный objViewer; затем лента Annotation монтируется и привязывается к тому же экземпляру.
Выпускайте пакеты аннотаций вместе с пакетами просмотрщика — они ограничены лицензией, поэтому теги появляются только при доступности возможности:
@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 видимой в разметке:
<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, затем создайте ленту только после того, как сервер подтвердит, что аннотация лицензирована:
<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, принадлежащей хосту:
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):
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).
Экспорт с встраиванием аннотаций
// 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 и сообщение об ошибке красным там, где должно быть изображение.
Рабочий процесс сохранения
- Откройте документ и получите его токен.
- Загрузите ранее сохранённый XML или закодированные данные в этот токен.
- Позвольте виджету прочитать и отредактировать аннотации сеанса.
- Получите XML с помощью
GetAnnotationXML(token), когда ваше приложение решит сохранить данные. - Экспортируйте PDF/PNG, когда требуется плоский результат.
- Закройте сеанс документа.
Не используйте непрозрачный токен просмотрщика в качестве постоянного идентификатора аннотации. Связывайте сохранённые данные аннотаций со своими собственными идентификаторами документа и версии.
Примечания по безопасности и рендерингу
- Запросы аннотаций используют ту же безопасность сеанса/токена, что и запросы страниц.
- Проверяйте и контролируйте любой пользовательский URL изображения, чтобы избежать подделки запросов на стороне сервера.
- Экспорты применяют те же решения по лицензии/пользовательскому водяному знаку, что и рендеринг страниц на экране.
- Большие свободные нагрузки и экспорт в высоком разрешении увеличивают использование памяти; тестируйте реальные документы и значения масштабирования.
Устранение неполадок
| Симптом | Проверка |
|---|---|
| Лента аннотаций отсутствует | Annotation возможность и четыре флага CSS/скриптов аннотации |
| Обратный вызов сохранения сообщает об ошибке | Истечение срока действия токена/сеанса и middleware BasePath |
ctlDoc_Created (или другая функция события) никогда не вызывается | Имя функции: id просмотрщика + _ + событие, как глобальная функция |
| Аннотации C# не отображаются | Нумерация страниц начинается с 1, и данные были загружены в активный токен |
| Аннотация изображения отображается на экране, но не в экспорте | Хост изображения имеет частный или loopback‑адрес — см. выше |
| Повторно открытый документ не содержит аннотаций | Сохраняйте XML/данные вне сеанса просмотрщика, затем загрузите их в новый токен |
Была ли эта страница полезной?