Переглядач

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

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Зарезервовано для окремо розповсюджуваного робочого процесу редактора; залиште 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 анотацій

Завантаження та експорт анотацій на боці сервера. Повний посібник знаходиться у 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)

Метод присутній для узгодження API, але переглядач DICOM у .NET 6 не може надати технічні теги. Він повертає 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 }))

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