Переглядач
Головний клас переглядача документів
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 має містити правильне розширення — воно визначає формат |
// Просте відкриття
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 (див. Основні концепції → Сесії та безпека). |
Клас також надає спеціалізовані властивості, які навмисно знаходяться поза звичайним потоком перегляду на одному хості:
| Тип | Властивість | За замовчуванням | Опис |
|---|---|---|---|
bool | IsWebFarm | false | Застаріло — не має ефекту. Публікуйте документ з DistributedDocumentPublisher.PublishAsync (або IDistributedPublishQueue.EnqueueAsync) і замість цього встановіть FileShareConfig.RootPath. |
string | WebFarmPath | "" | Застаріло — не має ефекту. Використовуйте FileShareConfig.RootPath замість цього. |
bool | EditMode | false | Зарезервовано для окремо розповсюджуваного робочого процесу Editor; залиште 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
});| Поле | Приклад | Значення |
|---|---|---|
Leading ^ | ^ | Необов’язкове розташування по всім кутам. Без нього використовується звичайне розміщення водяного знаку. |
| Text | Confidential | Текст, що відображається на кожній сторінці. Не повинен бути порожнім. |
| Color | 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) | Завантажити анотації з закодованого 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)Повертає метадані тегів DICOM для сесій, відкритих через плагін DICOM; null для не‑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 }))Чи була ця сторінка корисною?