Просмотрщик
Основной класс просмотра документов
Viewer (namespace Doconut) — публичная точка входа для открытия документов из Razor‑страниц, MVC‑контроллеров, компонентов Blazor или минимальных API. Он sealed, зарегистрирован как transient сервис AddDoconut(), и разрешается через внедрение через конструктор — никогда не создавайте его напрямую.
В предыдущей библиотеке .NET Standard был публичный конструктор, принимающий кэш памяти, аксессор HTTP‑контекста и один или несколько путей к лицензиям. Этот конструктор удалён; граф сервисов предоставляет эти зависимости.
Viewer не хранит состояние на каждый запрос и намеренно не реализует IDisposable: сеансы документов живут независимо в кэше сеанса, поэтому освобождение сервиса никогда не может закрыть открытый документ (см. Основные концепции → Как работает Viewer).
OpenDocumentAsync
Открывает документ и возвращает токен сеанса, который клиентский виджет использует для всех последующих запросов. Каждое открытие является асинхронным — синхронного OpenDocument нет.
| Перегрузка | Когда использовать |
|---|---|
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default) | Открытие с диска с автоматическим определением формата и конфигурацией по умолчанию формата |
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default) | Требуются параметры рендеринга для конкретного формата (PdfConfig, WordConfig, …) |
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default) | Документ не является файлом на диске (загрузка, база данных, блоб). fileInfo должен содержать правильное расширение — оно управляет определением формата |
// Простое открытие
string token = await viewer.OpenDocumentAsync(path);
// С конфигурацией и параметрами для каждого формата
token = await viewer.OpenDocumentAsync(
path,
new PdfConfig { AllowSearch = true, AllowCopy = true },
new DocOptions { TimeOut = 30 });
// Из загрузки
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));Исключения для обработки:
LicenseException— найденная лицензия отклоняется (сообщение содержит причину отклонения) или формат требует возможности плагина, которая больше не предоставляется. Истечение срока действия календаря без сообщения об отклонении приводит к рендерингу с водяным знаком вместо выброса исключения.FormatNotSupportedException—Document format '<extension>' is not supported.InvalidDataException— содержимое файла повреждено или не соответствует его расширению.
CloseDocument
void CloseDocument(string token)Удаляет сеанс из кэша (немедленно освобождая движок документа), удаляет маркер безопасности и отзывает предоставление доступа. Необязательно — скользящее истечение времени выполняет ту же очистку — но рекомендуется для больших документов.
GetPageCount
int GetPageCount(string token)Общее количество страниц открытого сеанса. Выбрасывает InvalidOperationException (Document session not found. Please re-open document.), если токен неизвестен или истёк, и ArgumentException для пустого токена.
GetPageDimensions
(int Width, int Height) GetPageDimensions(string token, int page = 1)Размер страницы документа по умолчанию при рендеринге с масштабом 100 % — пространство координат для аннотаций, построенных в коде. page принимается для совместимости; результат — значение по умолчанию документа. Выбрасывает InvalidOperationException (Document session not found. Please re-open document.), если токен неизвестен или истёк, и ArgumentException для пустого токена.
ПолучитьИменаЛистов
IReadOnlyList<string> GetWorksheetNames(string token)Возвращает имена листов открытой таблицы в порядке их расположения в книге, или пустой список, если открытый документ не является таблицей.
Перечисляются только отрисованные листы: скрытые и пустые листы исключаются, а когда ExcelConfig.SheetNames ограничивает отрисовку, отображаются только эти листы. Один лист не всегда соответствует одной странице — очень большой лист отрисовывается на нескольких страницах. Выбрасывает InvalidOperationException (Document session not found. Please re-open document.), если токен неизвестен или истёк, и ArgumentException для пустого токена.
Добавлено в версии 26.9.0.
Флаги возможностей
| Член | Значение |
|---|---|
bool IsSearchEnabled | Текущая лицензия предоставляет Search |
bool IsAnnotationEnabled | Текущая лицензия предоставляет Annotation |
Используйте их в Razor‑view для отображения лицензированной ленты только когда сервер действительно будет её обслуживать — см. Быстрый старт.
ПараметрыДокумента
Параметры, независимые от формата, применяемые при каждом открытии (пространство имён Doconut):
| Тип | Свойство | По умолчанию | Описание |
|---|---|---|---|
string | Password | "" | Пароль для защищённых документов (автоматически копируется в конфигурацию формата). |
int | ImageResolution | 0 | Устарело. Оставлено только для совместимости — вместо этого задайте ImageResolution в конфигурации формата. |
string | Watermark | "" | Пользовательский текст водяного знака, отображаемый на отрисованных страницах. Формат строки: "^Text~Color~FontSize~FontName~Opacity~Angle", например "^Sample Copy~Red~24~Verdana~80~-45". |
int | TimeOut | 60 | Скользящее время истечения сессии в минутах. |
bool | IsSecured | true | В настоящее время не применяется — зарезервировано. Привязка токена контролируется глобально через DoconutOptions.UnsafeMode (см. Основные концепции → Сессии и безопасность). |
Класс также предоставляет специализированные свойства, намеренно находящиеся вне обычного одностороннего потока просмотра:
| Тип | Свойство | По умолчанию | Описание |
|---|---|---|---|
bool | IsWebFarm | false | Устарело — не имеет эффекта. Публикуйте документ с помощью DistributedDocumentPublisher.PublishAsync (или IDistributedPublishQueue.EnqueueAsync) и вместо этого задайте FileShareConfig.RootPath. Обратите внимание на регистр — в предыдущей библиотеке это было IsWebfarm. |
string | WebFarmPath | "" | Устарело — не имеет эффекта. Используйте FileShareConfig.RootPath, как описано в Распределённые развертывания. Ранее назывался WebfarmPath. |
bool | EditMode | false | Зарезервировано для отдельного распределённого рабочего процесса редактирования; оставьте false для стандартного просмотрщика. |
Пользовательский водяной знак
DocOptions.Watermark использует шесть полей, разделённых тильдами. Необязательный начальный ^ запрашивает расположение по всем углам:
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Поле | Пример | Значение |
|---|---|---|
Ведущий ^ | ^ | Необязательное расположение по всем углам. Без него используется обычное размещение водяного знака. |
| Текст | Confidential | Текст, отображаемый на каждой странице. Не может быть пустым. |
| Цвет | Red | Именованный цвет, понятный слою отрисовки. |
| РазмерШрифта | 24 | Размер шрифта; неверный числовой ввод приводит к использованию значения по умолчанию рендерера. |
| ИмяШрифта | Verdana | Запрашиваемое семейство шрифтов. Убедитесь, что оно установлено в среде развертывания. |
| Прозрачность | 80 | Значение байта от 0 до 255. Должно успешно парситься. |
| Угол | -45 | Угол вращения в градусах; неверный числовой ввод приводит к использованию значения по умолчанию. |
Парсер ожидает ровно шесть полей после необязательного ^. Неверное определение заменяется видимым резервным вариантом SDK Invalid Watermark вместо того, чтобы исчезнуть без предупреждения.
Решение о лицензии
| Состояние лицензии | Пользовательское значение предоставлено | Отображаемый результат |
|---|---|---|
| Действительная платная лицензия просмотрщика | Нет | Чистая страница |
| Действительная платная лицензия просмотрщика | Да | Пользовательский водяной знак |
| Активный временный/демо базовый просмотрщик | Нет | Чистая страница базового просмотрщика |
| Активный временный/демо базовый просмотрщик | Да | Пользовательский водяной знак, когда применяется путь чистого базового просмотрщика |
| Отсутствующая, отклонённая, просроченная, неверной версии или недействительная лицензия домена | Любой | Водяной знак принудительного/оценочного контроля; пользовательское значение не переопределяет его |
| Отрисовка плагина по правилам оценки | Любой | Водяной знак оценки |
То же решение применяется к обслуживаемым изображениям страниц и экспортам аннотаций. Вывод анимированных GIF помечается кадр за кадром. Пользовательский водяной знак, следовательно, является функцией лицензированного приложения, а не способом заменить или подавить оценочный водяной знак.
API аннотаций
Загрузка и экспорт аннотаций на стороне сервера. Полный пошаговый гид находится в Руководства → Аннотации; интерфейс выглядит так:
| Элемент | Назначение |
|---|---|
AnnotationManager GetAnnotationManager(string token) | Менеджер, привязанный к размерам страницы открытой сессии |
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight) | Менеджер с явными размерами страницы |
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight) | Менеджер, независимый от сессии |
void LoadAnnotationData(string token, AnnotationManager manager) | Загрузка аннотаций, построенных на C#, в сессию |
void LoadAnnotationData(string token, string annotationData) | Загрузка аннотаций из закодированной страницы/конверта Base64, возвращённого AnnotationManager.GetAnnotationData() |
void LoadAnnotationXML(string token, XmlDocument annotationXml) | Загрузка аннотаций из XML |
XmlDocument GetAnnotationXML(string token) | Экспорт аннотаций сессии в виде XML |
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default) | PDF с внедрёнными аннотациями |
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | Один PNG на страницу, аннотации внедрены, записываются в directoryPath (создаётся при отсутствии); возвращает количество записанных изображений |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | ZIP с PNG‑файлами по страницам, в которые внедрены аннотации |
Каждый из этих методов принимает токен сессии. Форма GetAnnotationManager(pageWidth, pageHeight) без сессии из предыдущей библиотеки сохраняется для создания аннотаций вне сессии, однако их загрузка всё равно требует токен.
Метаданные DICOM
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)Метод присутствует для согласования API, но этот пакет не может предоставить технические теги DICOM: считыватель метаданных поставляется только в сборке .NET 8. Он возвращает null для DICOM и недICOM‑сессий; в DICOM‑сессии также выводит одноразовое предупреждение, объясняющее ограничение платформы. Отрисовка страниц, кадров и анимаций остаётся поддерживаемой.
Вспомогательные ресурсы — ReferenceCss / ReferenceScripts
Выводите теги <link>/<script> для встроенных ресурсов, обслуживаемых UseDoconutResources(), в правильном порядке зависимостей. Пакеты для функций, ограниченных лицензией, таких как поиск и аннотация, выводятся только когда лицензия их разрешает, поддерживая согласованность UI клиента с поведением сервера.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + viewer + поиск + аннотация
string ReferenceScripts(ScriptConfig? config = null)Флаги CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (ограничено поиском), IncludeAnnotationCss (ограничено аннотацией).
Флаги ScriptConfig: IncludeJQuery (требуется всеми остальными), IncludeBootstrap, IncludeViewerScripts (ядро: docViewer.js + splitter + links), IncludeSearchScripts и IncludeSearchBar (ограничено поиском), IncludeAnnotationScripts и IncludeAnnotationBar (ограничено аннотацией), EmitFeatureFlags (по умолчанию true: также записывает встроенный скрипт window.Doconut.features = { search, annotation, editor }; установите его в false при Content-Security-Policy, блокирующей встроенные скрипты).
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))Эти вспомогательные средства — поддерживаемый способ доставки ресурсов браузера. Приложения, которые скопировали docViewer.js, documentLinks.js и docViewer.UI.js в wwwroot, должны удалить эти копии после того, как страница будет отрисована с помощью выводимых тегов.
Была ли эта страница полезной?