Переглядач

Головний клас переглядача документів

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

Попередня бібліотека .NET Standard надавала публічний конструктор, який приймав кеш пам’яті, доступ до HTTP‑контексту та один або кілька шляхів до ліцензій. Цей конструктор більше не існує; граф сервісів постачає ці залежності.

Viewer не містить стану, пов’язаного з окремим запитом, і навмисно не реалізує IDisposable: сеанси документів живуть незалежно в кеші сеансів, тому знищення сервісу ніколи не може закрити відкритий документ (див. Основні концепції → Як працює переглядач).

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)Документ не є файлом на диску (завантаження, база даних, blob). 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. Зверніть увагу на регістр — у попередній бібліотеці це було написано як 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Іменований колір, який розуміє шар малювання.
FontSize24Розмір шрифту; недійсний числовий ввід повертається до типового значення рендерера.
FontNameVerdanaЗапитувана сімейство шрифтів. Переконайтеся, що воно встановлене у середовищі розгортання.
Opacity80Значення байта від 0 до 255. Має успішно розбиратись.
Angle-45Кут обертання у градусах; недійсний числовий ввід повертається до типового значення.

Парсер очікує саме шість полів після необов’язкового ^. Недійсне визначення замінюється видимим запасним варіантом SDK Invalid Watermark замість того, щоб безшумно зникнути.

Рішення щодо ліцензії

Стан ліцензіїНадане користувачем значенняРезультат рендерингу
Дійсна платна ліцензія переглядачаНіЧиста сторінка
Дійсна платна ліцензія переглядачаТакКористувацький водяний знак
Активний тимчасовий/демо базовий переглядачНіЧиста сторінка базового переглядача
Активний тимчасовий/демо базовий переглядачТакКористувацький водяний знак, коли застосовується шлях чистого базового переглядача
Відсутня, відхилена, прострочена, неправильна версія або ліцензія недійсного доменуБудь-якаВодяний знак примусу/оцінки; користувацьке значення його не замінює
Рендеринг плагіна за правилами оцінкиБудь-якаВодяний знак оцінки

Те саме рішення застосовується до зображень сторінок, що подаються, та експорту анотацій. Вивід анімованих GIF‑файлів маркується кадр за кадром. Таким чином, користувацький водяний знак є функцією ліцензованого застосунку, а не способом замінити чи придушити водяний знак оцінки.

API анотацій

Завантаження та експорт анотацій на боці сервера. Повний посібник знаходиться в Guides → Annotations; інтерфейс виглядає так:

ЧленПризначення
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(), у правильному порядку залежностей. Пакети для функцій, що залежать від ліцензії, таких як пошук і анотації, виводяться лише коли ліцензія їх дозволяє, зберігаючи узгодженість інтерфейсу клієнта з поведінкою сервера.

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

Ці допоміжні засоби — підтримуваний спосіб доставки ресурсів браузера. Додатки, які скопіювали docViewer.js, documentLinks.js та docViewer.UI.js у wwwroot, повинні видалити ці копії, як тільки сторінка буде відображена за допомогою виведених тегів.

Чи була ця сторінка корисною?