Просмотрщик
Основной класс просмотра документов
Viewer (namespace Doconut) является публичной точкой входа для открытия документов из Razor‑страниц, MVC‑контроллеров, компонентов Blazor или минимальных API. Он sealed, зарегистрирован как transient сервис AddDoconut() и разрешается через внедрение через конструктор — никогда не создавайте его напрямую.
Viewer не хранит состояние на запрос и намеренно не реализует IDisposable: сеансы документов живут независимо в кэше сеансов, поэтому освобождение сервиса никогда не может закрыть открытый документ (см. Основные концепции → Как работает Viewer).
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 должен содержать правильное расширение — оно определяет формат |
// Простое открытие
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 для пустого токена.
GetWorksheetNames
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 для отображения лицензированной ленты только тогда, когда сервер действительно будет её обслуживать — см. Быстрый старт.
Параметры DocOptions
Опции, независимые от формата, применимые к каждому открытию (пространство имён 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 (см. Core Concepts → Sessions & Security). |
Класс также предоставляет специализированные свойства, которые намеренно находятся вне обычного однопользовательского потока просмотра:
| Тип | Свойство | Значение по умолчанию | Описание |
|---|---|---|---|
bool | IsWebFarm | false | Устарело — не оказывает влияния. Публикуйте документ с помощью DistributedDocumentPublisher.PublishAsync (или IDistributedPublishQueue.EnqueueAsync) и вместо этого установите FileShareConfig.RootPath. |
string | WebFarmPath | "" | Устарело — не оказывает влияния. Вместо этого используйте FileShareConfig.RootPath. |
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
});| Поле | Пример | Значение |
|---|---|---|
Ведущий ^ | ^ | Необязательное расположение во всех углах. Без него используется обычное размещение водяного знака. |
| Text | Confidential | Текст, отображаемый на каждой странице. Не должен быть пустым. |
| Color | Red | Именованный цвет, понятный слою рисования. |
| FontSize | 24 | Размер шрифта; некорректный числовой ввод приводит к использованию значения по умолчанию рендерера. |
| FontName | Verdana | Запрашиваемое семейство шрифтов. Убедитесь, что оно установлено в среде развертывания. |
| Opacity | 80 | Значение байта от 0 до 255. Должно успешно парситься. |
| Angle | -45 | Угол вращения в градусах; некорректный числовой ввод приводит к использованию значения по умолчанию. |
Парсер ожидает ровно шесть полей после необязательного ^. Некорректное определение заменяется видимым резервным Invalid Watermark из SDK вместо тихого исчезновения.
Решение о лицензии
| Состояние лицензии | Пользовательское значение предоставлено | Отрисованный результат |
|---|---|---|
| Действительная платная лицензия просмотрщика | Нет | Чистая страница |
| Действительная платная лицензия просмотрщика | Да | Пользовательский водяной знак |
| Активный временный/демо базовый просмотрщик | Нет | Чистая страница базового просмотрщика |
| Активный временный/демо базовый просмотрщик | Да | Пользовательский водяной знак, когда применяется путь чистого базового просмотрщика |
| Отсутствующая, отклонённая, просроченная, неверной версии или с неверным доменом лицензия | Любая | Водяной знак принудительного/оценочного применения; пользовательское значение не переопределяет его |
| Отрисовка плагина по правилам оценки | Любая | Оценочный водяной знак |
То же решение применяется к обслуживаемым изображениям страниц и экспортам аннотаций. Вывод анимированного 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
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)Метод присутствует для согласования API, но просмотрщик DICOM на .NET 6 не может предоставить технические теги. Он возвращает null для DICOM и не‑DICOM сессий; в DICOM‑сессии также выводит одноразовое предупреждение, объясняющее ограничение платформы. Отрисовка страниц, кадров и анимаций остаётся поддерживаемой.
Вспомогательные ресурсы — ReferenceCss / ReferenceScripts
Выводите теги <link>/<script> для встроенных ресурсов, обслуживаемых UseDoconutResources(), в правильном порядке зависимостей. Пакеты для функций, ограниченных лицензией, таких как поиск и аннотация, выводятся только когда лицензия их разрешает, поддерживая согласованность UI клиента с поведением сервера.
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, блокирующей встроенные скрипты).
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))Была ли эта страница полезной?