Переглядач
Головний клас переглядача документів
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 має містити правильне розширення — воно визначає формат |
// Просте відкриття
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‑виді, щоб відображати ліцензовану стрічку лише тоді, коли сервер дійсно її надає — дивіться Швидкий старт.
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. Зверніть увагу на регістр — у попередній бібліотеці це було написано як IsWebfarm. |
string | WebFarmPath | "" | Застаріло — не має ефекту. Використовуйте FileShareConfig.RootPath, як описано у Розподілених розгортаннях. Раніше це писалося як WebfarmPath. |
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
});| Поле | Приклад | Значення |
|---|---|---|
Початковий ^ | ^ | Необов’язкове розташування по всім кутам. Якщо його немає, використовується звичайне розміщення водяного знака. |
| Текст | Confidential | Текст, що відображається на кожній сторінці. Не повинен бути порожнім. |
| Колір | Red | Іменований колір, який розуміє шар малювання. |
| FontSize | 24 | Розмір шрифту; недійсний числовий ввід повертається до типового значення рендерера. |
| FontName | Verdana | Запитувана сімейство шрифтів. Переконайтеся, що воно встановлене у середовищі розгортання. |
| Opacity | 80 | Значення байта від 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
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)Метод присутній для узгодження API, проте цей пакет не може надати технічні теги DICOM: читач метаданих постачається лише у збірці .NET 8. Він повертає null для DICOM та недICOM сесій; у DICOM сесії також виводить одноразове попередження, що пояснює обмеження платформи. Рендеринг сторінок, кадрів та анімацій залишається підтримуваним.
Допоміжні ресурси — ReferenceCss / ReferenceScripts
Виводьте теги <link>/<script> для вбудованих ресурсів, що подаються UseDoconutResources(), у правильному порядку залежностей. Пакети для функцій, що залежать від ліцензії, таких як пошук і анотації, виводяться лише коли ліцензія їх дозволяє, зберігаючи узгодженість інтерфейсу клієнта з поведінкою сервера.
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 }))Ці допоміжні засоби — підтримуваний спосіб доставки ресурсів браузера. Додатки, які скопіювали docViewer.js, documentLinks.js та docViewer.UI.js у wwwroot, повинні видалити ці копії, як тільки сторінка буде відображена за допомогою виведених тегів.
Чи була ця сторінка корисною?