Просмотрщик

Основной класс просмотрщика документов

Viewer (namespace Doconut) является публичной точкой входа для открытия документов из Razor‑страниц, MVC‑контроллеров, компонентов Blazor или минимальных API. Он sealed, зарегистрирован как transient сервис AddDoconut(), и разрешается через внедрение через конструктор — никогда не создавайте его напрямую.

Viewer не содержит состояния, зависящего от запроса, и намеренно не реализует IDisposable: сеансы документов живут независимо в кэше сеансов, поэтому удаление сервиса никогда не может закрыть открытый документ (см. Core Concepts → How the Viewer Works).

OpenDocumentAsync

Открывает документ и возвращает токен сеанса, который клиентский виджет использует для всех последующих запросов.

ПерегрузкаКогда использовать
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 должен содержать правильное расширение — оно определяет формат
csharp
// Простое открытие
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

text
void CloseDocument(string token)

Удаляет сеанс из кэша (немедленно освобождая движок документа), удаляет маркер безопасности и отзывает предоставление доступа. Необязательно — скользящее истечение времени выполняет ту же очистку — но рекомендуется для больших документов.

GetPageCount

text
int GetPageCount(string token)

Общее количество страниц открытого сеанса. Выбрасывает InvalidOperationException (Document session not found. Please re-open document.), если токен неизвестен или истёк, и ArgumentException для пустого токена.

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

Размер страницы документа по умолчанию при 100 % масштабе — координатное пространство для аннотаций, построенных в коде. page принимается для совместимости; результат — значение по умолчанию документа. Выбрасывает InvalidOperationException (Document session not found. Please re-open document.), если токен неизвестен или истёк, и ArgumentException для пустого токена.

GetWorksheetNames

text
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, чтобы отобразить лицензированную ленту только тогда, когда сервер действительно будет её обслуживать — см. Быстрый старт.

DocOptions

Опции, независимые от формата, применяемые при каждом открытии (пространство имён Doconut):

ТипСвойствоПо умолчаниюОписание
stringPassword""Пароль для защищённых документов (автоматически копируется в конфигурацию формата).
intImageResolution0Устарело. Сохраняется только для совместимости — вместо этого установите ImageResolution в конфигурации формата.
stringWatermark""Пользовательский текст водяного знака, отображаемый на отрисованных страницах. Формат строки: "^Text~Color~FontSize~FontName~Opacity~Angle", например "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60Скользящее истечение сессии в минутах.
boolIsSecuredtrueВ настоящее время не применяется — зарезервировано. Привязка токенов контролируется глобально через DoconutOptions.UnsafeMode (см. Core Concepts → Sessions & Security).

Класс также предоставляет специализированные свойства, которые намеренно находятся вне обычного потока просмотра единственного хоста:

ТипСвойствоПо умолчаниюОписание
boolIsWebFarmfalseУстарело — не имеет эффекта. Публикуйте документ с помощью DistributedDocumentPublisher.PublishAsync (или IDistributedPublishQueue.EnqueueAsync) и вместо этого установите FileShareConfig.RootPath.
stringWebFarmPath""Устарело — не имеет эффекта. Вместо этого используйте FileShareConfig.RootPath.
boolEditModefalseЗарезервировано для отдельного распределённого рабочего процесса редактора; оставьте false для стандартного просмотрщика.

Пользовательский водяной знак

DocOptions.Watermark использует шесть полей, разделённых тильдами. Необязательный ведущий ^ запрашивает расположение по всем углам:

text
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string 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)Загружает аннотации из закодированного page/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 по страницам с вшитыми аннотациями

Метаданные DICOM

text
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

Возвращает метаданные тегов DICOM для сессий, открытых через плагин DICOM; null для не‑DICOM документов.

Вспомогательные ресурсы — ReferenceCss / ReferenceScripts

Создаёт теги <link>/<script> для встроенных ресурсов, обслуживаемых UseDoconutResources(), в правильном порядке зависимостей. Пакеты для функций, ограниченных лицензией, таких как поиск и аннотация, генерируются только когда лицензия их разрешает, поддерживая согласованность пользовательского интерфейса клиента с поведением сервера.

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + просмотр + поиск + аннотация
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, блокирующей встроенные скрипты).

html
@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

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