Просмотрщик

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

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

ПолучитьИменаЛистов

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

ПараметрыДокумента

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

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

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

ТипСвойствоПо умолчаниюОписание
boolIsWebFarmfalseУстарело — не имеет эффекта. Публикуйте документ с помощью DistributedDocumentPublisher.PublishAsync (или IDistributedPublishQueue.EnqueueAsync) и вместо этого задайте FileShareConfig.RootPath. Обратите внимание на регистр — в предыдущей библиотеке это было IsWebfarm.
stringWebFarmPath""Устарело — не имеет эффекта. Используйте FileShareConfig.RootPath, как описано в Распределённые развертывания. Ранее назывался WebfarmPath.
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)Загрузка аннотаций из закодированной страницы/конверта 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

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

Метод присутствует для согласования API, но этот пакет не может предоставить технические теги DICOM: считыватель метаданных поставляется только в сборке .NET 8. Он возвращает null для DICOM и недICOM‑сессий; в DICOM‑сессии также выводит одноразовое предупреждение, объясняющее ограничение платформы. Отрисовка страниц, кадров и анимаций остаётся поддерживаемой.

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

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

text
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, блокирующей встроенные скрипты).

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 }))

Эти вспомогательные средства — поддерживаемый способ доставки ресурсов браузера. Приложения, которые скопировали docViewer.js, documentLinks.js и docViewer.UI.js в wwwroot, должны удалить эти копии после того, как страница будет отрисована с помощью выводимых тегов.

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