Переглядач
Основний клас переглядача документів
Viewer (namespace Doconut) є публічною точкою входу для відкриття документів з контролерів MVC, сторінок Web Forms та обробників. Це транзієнтний сервіс, складений з DoconutHost.Initialize; отримайте його там, де ви його використовуєте:
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();new Viewer() також працює після того, як DoconutHost.Initialize запущено — він вирішує ті ж сервіси — що дозволяє коду, перенесеному з класичного пакету, компілюватися. До Initialize він викидає InvalidOperationException.
Viewer не містить стану документа per-request і навмисно не реалізує IDisposable: сесії документів живуть незалежно від нього, тому звільнення Viewer ніколи не закриє відкритий документ (див. Як працює переглядач).
OpenDocumentAsync
Відкриває документ і повертає токен сесії, який віджет використовує для всіх подальших запитів. Коли UnsafeMode є false (за замовчуванням), токен надається ASP.NET сесії поточного запиту — викликайте його з запиту, що має стан сесії (див. Сесії та безпека).
| Перевантаження | Коли використовується |
|---|---|
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) | Документ не є файлом на диску (завантаження, база даних, блоб). fileInfo має мати правильне розширення — воно визначає формат |
// Просте відкриття
string token = await viewer.OpenDocumentAsync(path);
// З налаштуванням та параметрами для кожного формату
token = await viewer.OpenDocumentAsync(
path,
new PdfConfig { AllowSearch = true, AllowCopy = true },
new DocOptions { TimeOut = 30 });
// З завантаження (HttpPostedFileBase у MVC; HttpPostedFile у Web Forms)
using (var ms = new MemoryStream())
{
await file.InputStream.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}Винятки для обробки:
LicenseException— ліцензію знайдено, але вона відхилена (повідомлення містить причину), або формат потребує можливості плагіна, яку ліцензія не надає.FormatNotSupportedException— жоден переглядач не підтримує розширення файлу.InvalidDataException— вміст пошкоджений або не відповідає його розширенню.
OpenDocument (synchronous)
Для коду позаду Web Forms та іншого коду, який не використовує асинхронні сторінки:
string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)Кожен повертає токен і також зберігає його в viewer.Token. fileName має мати правильне розширення. Ці обгортки безпечно викликати зі сторінки Web Forms: шлях відкриття ніколи не відновлюється у контексті запиту ASP.NET, тому очікування не може призвести до блокування. Те ж саме не стосується кожного асинхронного Doconut API — див. розділ Web Forms у Плагіні конвертера.
CloseDocument
void CloseDocument(string token)Видаляє сесію (негайно звільняючи движок документа), видаляє надання токену з ASP.NET‑сесії поточного запиту та анулює токен. Необов’язково — скользяче закінчення виконує те ж очищення — проте рекомендується для великих документів.
Запити сесії
| Член | Повертає |
|---|---|
int GetPageCount(string token) | Загальна кількість сторінок відкритого документа |
(int Width, int Height) GetPageDimensions(string token, int page = 1) | Типовий розмір відображеної сторінки при 100 % масштабі — простір координат для анотацій, створених у коді |
IReadOnlyList<string> GetWorksheetNames(string token) | Відображені листи електронної таблиці у порядку книги; порожньо для інших документів |
Кожен генерує InvalidOperationException (Document session not found. Please re-open document.), якщо токен невідомий або прострочений, і ArgumentException для порожнього токену.
ПараметриДокументу
Параметри, незалежні від формату, для кожного відкриття (простір імен Doconut):
| Тип | Властивість | За замовчуванням | Опис |
|---|---|---|---|
string | Password | "" | Пароль для захищених документів (автоматично копіюється у конфігурацію формату). |
string | Watermark | "" | Власний текст водяного знака, намальований на відображених сторінках — дивіться нижче. |
int | TimeOut | 60 | Скользяче закінчення сесії, у хвилинах. |
string | BrowserId | "" | Веб‑ферми: браузер, до якого прив’язаний підписаний квиток. Встановіть його за допомогою DoconutFarmBinding.EnsureBrowserId (див. Сесії та безпека). |
string | UserId | "" | Веб‑ферми: користувач, до якого прив’язаний підписаний квиток, з DoconutFarmBinding.ResolveUserId. |
int | ImageResolution | 0 | Застаріле. Натомість встановіть ImageResolution у конфігурації формату. |
bool | IsSecured | true | Зарезервовано; не застосовується. Керування доступом — DoconutOptions.UnsafeMode. |
bool | IsWebFarm / string WebFarmPath | false / "" | Збережено для коду, перенесеного з класичного пакету. Вони не вмикають режим ферми — AddDoconutDistributed робить це. |
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
});| Поле | Приклад | Значення |
|---|---|---|
Leading ^ | ^ | Необов’язкове розташування у всіх кутах. Без нього використовується звичайне розміщення. |
| Text | Confidential | Текст, намальований на кожній сторінці. Не повинен бути порожнім. |
| Color | Red | Названа колір. |
| FontSize | 24 | Розмір шрифту; неправильне числове значення повертається до значення за замовчуванням. |
| FontName | Verdana | Сімейство шрифтів. Має бути встановлене на сервері — у Windows Server менше шрифтів, ніж на настільному комп’ютері. |
| Opacity | 80 | 0 до 255. Має бути коректним. |
| Angle | -45 | Поворот у градусах; неправильне числове значення повертається до значення за замовчуванням. |
Парсер очікує точно шість полів після необов’язкового ^. Неправильне визначення замінюється видимим текстом Invalid Watermark замість того, щоб безшумно зникнути.
Рішення щодо ліцензії
| Стан ліцензії | Надане користувацьке значення | Відображений результат |
|---|---|---|
| Дійсна платна ліцензія переглядача | Ні | Чиста сторінка |
| Дійсна платна ліцензія переглядача | Так | Користувацький водяний знак |
| Активна тимчасова/демо‑ліцензія | Ні | Чиста сторінка |
| Активна тимчасова/демо‑ліцензія | Так | Користувацький водяний знак |
| Відсутня, відхилена, прострочена, неправильна версія або недійсна доменна ліцензія | Будь-яка | Водяний знак оцінки; користувацьке значення його не замінює. |
Те саме рішення застосовується до наданих сторінок та до експорту анотацій. Користувацький водяний знак є функцією ліцензованого застосунку, а не способом замінити водяний знак оцінки.
API анотацій
Завантаження та експорт анотацій на боці сервера. Посібник доступний у розділі Анотації.
| Член | Призначення |
|---|---|
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) | Завантажити закодований конверт, повернутий 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)У цьому пакеті він завжди повертає null, а запит метаданих віджету відповідає 501 Not Implemented: читання DICOM‑тегів недоступне у .NET Framework. DICOM rendering — сторінки, кадри та анімація — працює. Дивіться Плагін DICOM.
Помічники ресурсів — ReferenceCss / ReferenceScripts
Вивести теги <link> та <script> для ресурсів, які модуль ресурсів надає під DoconutOptions.ResourcesPath, у порядку залежностей. Файли для функцій, що потребують ліцензії (Search, Annotation), виводяться лише коли ліцензія їх надає.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + переглядач + пошук + анотація
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; } // стан ліцензії, для захисту коду ініціалізації стрічки
bool IsAnnotationEnabled { get; }CssConfig прапорці: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (залежний від пошуку), IncludeAnnotationCss (залежний від анотації).
ScriptConfig прапорці: IncludeJQuery (необхідний для всіх інших), IncludeBootstrap, IncludeViewerScripts (основні скрипти переглядача), IncludeSearchScripts та IncludeSearchBar (залежний від пошуку), IncludeAnnotationScripts та IncludeAnnotationBar (залежний від анотації), EmitFeatureFlags (за замовчуванням true: також записує вбудований скрипт window.Doconut.features = { search, annotation, editor }; встановіть його в false за політикою Content‑Security‑Policy, що блокує вбудовані скрипти).
Обидва повертають HTML: використовуйте @Html.Raw(...) у MVC 5 (генеруйте їх у контролері — у представлень немає @inject) або <%= %> у Web Forms. Швидкий старт показує обидва варіанти.
RenderViewer
string RenderViewer(string elementId, string token, ViewerConfig? config = null)Повертає блок <script>, який ініціалізує віджет у елементі з id elementId і відображає документ: docViewer({...}), створений з ViewerConfig (за замовчуванням: BasePath: '/', ResPath: 'doconut-res/images'), потім .View(token). Додайте його після скриптів переглядача. Згенерований скрипт не зберігає посилання на об’єкт переглядача, тому сторінка зі своєю панеллю інструментів повинна ініціалізувати віджет вручну. Дивіться Конфігурація переглядача.
Веб‑ферма
string? AccessToken містить підписаний квиток, виданий останнім відкриттям, коли активний розподілений режим, і UnsafeMode є false; на одному сервері він є null. Надішліть його у віджет разом з токеном: objViewer.View(token, accessToken).
Чи була ця сторінка корисною?