Переглядач

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

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)Документ не є файлом на диску (завантаження, база даних, 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 (див. Основні концепції → Сесії та безпека).

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

ТипВластивістьЗа замовчуваннямОпис
boolIsWebFarmfalseЗастаріло — не має ефекту. Публікуйте документ з DistributedDocumentPublisher.PublishAsync (або IDistributedPublishQueue.EnqueueAsync) і замість цього встановіть FileShareConfig.RootPath.
stringWebFarmPath""Застаріло — не має ефекту. Використовуйте FileShareConfig.RootPath замість цього.
boolEditModefalseЗарезервовано для окремо розповсюджуваного робочого процесу Editor; залиште 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
    });
ПолеПрикладЗначення
Leading ^^Необов’язкове розташування по всім кутам. Без нього використовується звичайне розміщення водяного знаку.
TextConfidentialТекст, що відображається на кожній сторінці. Не повинен бути порожнім.
ColorRedІменований колір, зрозумілий шаром малювання.
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)Завантажити анотації з закодованого 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 }))

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