Швидкий старт
Відобразіть свій перший документ за кілька хвилин
Цей посібник переводить додаток ASP.NET Core від порожнього Program.cs до документу, що відображається у браузері: реєстрація сервера, повний пакет Viewer (панель інструментів Viewer, монтування Viewer та необов’язкові стрічки Пошуку/Анотації), посилання на ресурси, ініціалізація клієнта, відкриття документу та виконання.
Хост-додаток повинен орієнтуватися на середовище виконання, яке підтримує netstandard2.1 — .NET Core 3.0 або новіше.
Налаштування сервера
AddDoconut() реєструє служби; UseDoconutResources() і UseDoconut() підключають middleware. Виклик ресурсів має бути першим. UseDoconut() відповідає на кожен запит, що до нього надходить, тому змонтуйте його на окремій гілці за допомогою app.Map. Виклики сесії також потрібні — стандартна безпека документу Doconut перевіряє кожен запит сторінки проти стану сесії ASP.NET. Стан сесії потребує кешу: AddDistributedMemoryCache() його надає. Додаток MVC або Razor Pages вже реєструє його, але мінімальний API‑додаток — ні, і без нього додаток зупиняється під час запуску з Unable to resolve service for type 'IDistributedCache'. Вже реєстрували Doconut під час Installation? Перейдіть до наступного розділу.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // стан сеансу потребує кешу (MVC/Razor Pages вже додає його)
builder.Services.AddSession(); // Doconut безпека документу базується на ASP.NET стані сеансу
app.UseSession(); // викличте UseSession() перед UseDoconut()
app.UseDoconutResources(); // повинно бути зареєстровано перед UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());Це налаштування зберігає історичну форму запиту DocImage.axd і монтує
middleware документу на відповідній гілці. Це розташування, яке слід копіювати, коли ви
переносите існуючий додаток .NET Standard, оскільки клієнт продовжує викликати
той самий URL, який завжди використовував:
builder.Services.AddDoconut(options =>
{
options.UnsafeMode = false; // зберігайте перевірку сесії Doconut увімкненою
options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // стан сеансу потребує кешу (MVC/Razor Pages вже додає його)
builder.Services.AddSession(options =>
{
options.IdleTimeout = TimeSpan.FromSeconds(3600);
options.Cookie.HttpOnly = true;
options.Cookie.IsEssential = true;
});
// Потрібно для багатобайтових кодувань у деяких форматах документів.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources(); // ПЕРЕД гілкою документу
app.MapWhen(
context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconut() не приймає параметрів у цьому випуску — все перенесено до AddDoconut().
MiddlewarePath є координуючим значенням; воно не прив’язує гілку ASP.NET Core самостійно. За допомогою гілки DocImage.axd вище, клієнт використовує BasePath: '/'; з app.Map("/doconut", ...) з мінімального налаштування, він використовує BasePath: 'doconut'.
ResourcesPath надає вбудований пакет за адресою /doconut-res, а шлях до ресурсів зображень віджету тому є ResPath: 'doconut-res/images'.
Додайте переглядач на сторінку
Viewer є необхідним ядром сторінки. Його поверхня рендерингу використовує два вкладені divs:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Розглядайте панель інструментів, монтування модулів та поверхню Viewer як одну композицію сторінки. Пошук і Анотація вбудовують свої стрічки у необов’язкові монтування, проте ці модулі ніколи не працюють окремо: вони завжди підключаються до Viewer на тій самій сторінці.
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Кнопки навігації переглядача, масштабування, пошуку та анотації -->
</nav>
<div id="searchBarMount"></div>
<div id="annBarMount"></div>
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Посилання на ресурси переглядача
У Razor‑виді інжектований сервіс Viewer генерує теги <link> та <script> переглядача у правильному порядку залежностей — віджет є jQuery‑плагіном, тому jQuery має бути завантажений перед скриптами переглядача:
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true
}))Для повного пакету Viewer запитуйте ресурси Viewer та модулів разом:
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true,
IncludeSearchCss = true,
IncludeAnnotationCss = true
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true,
IncludeSearchScripts = true,
IncludeSearchBar = true,
IncludeAnnotationScripts = true,
IncludeAnnotationBar = true
}))IncludeViewerCss та IncludeViewerScripts — це обов'язкові базові прапорці. Ніколи не публікуйте приклад Search або Annotation Ribbon без них, без монтування Viewer та без екземпляра docViewer. ReferenceCss та ReferenceScripts пропускають ресурси необов'язкового модуля, коли поточна ліцензія не надає таку можливість; ядро Viewer все одно запускається.
Ці виклики замінюють вручну скопійовані файли скриптів. Якщо застосунок все ще завантажує власні docViewer.js, documentLinks.js або docViewer.UI.js, видаліть ці теги, коли сторінка працює з виданих ресурсів — дивіться посібник з міграції.
Ініціалізація переглядача
Клієнтський віджет є jQuery‑плагіном. Ось мінімальний набір реальних параметрів ініціалізації (не псевдокод):
let searchBar = null;
let annBar = null;
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: '/', // гілка DocImage.axd; 'doconut' з app.Map("/doconut", ...)
ResPath: 'doconut-res/images',
onViewerReady: function () {
// сторінки видимі; безпечно приховати індикатор завантаження тут
},
// Перенаправляти події життєвого циклу анотації до вбудованої стрічки, коли вона присутня.
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});Чотири деталі визначають, чи працює ця сторінка взагалі:
- Зворотні виклики — це параметри.
onViewerReady,onViewerBusy,onCopyіonAutoLoadStatusпередаються в об’єкт параметрів. Попередній переглядач отримував імена глобальних функцій з id контейнера і викликав їх; цей цього не робить. Обробник, оголошений лише як глобальна функція, ніколи не виконується, і про це не повідомляється. ResPathвказує на префікс ресурсів, а не на корінь застосунку. За замовчуваннямResourcesPath, це значення —doconut-res/images. Якщо ви змінилиResourcesPath, використайте власний префікс. Іконки розташовані на одну папку нижче кореня ресурсів: з'doconut-res'кожна іконка повертає 404, хоча сам документ все ще відображається.BasePathне має початкового слешу окрім значення кореня сайту'/'.'doconut'запитує/doconut/DocImage.axd;'/doconut'генерує//doconut/DocImage.axd, який браузер сприймає як запит до іншого хоста.- Залиште переглядач, а потім викличте
Viewокремо.docViewer(...)повертає об’єкт зZoom,NextтаFitType;View(...)повертає інше.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)відображає документ, а потім падає зobjViewer.Zoom is not a functionпри першому кліку на панелі інструментів.
Усі ці помилки відбуваються без повідомлень — дивіться Усунення проблем та посібник з міграції.
Регістр параметрів дійсно змішаний — showThumbs, autoLoad і pageZoom написані у camelCase, а FitType, BasePath і ResPath — у PascalCase. Немає послідовного правила; якщо регістр вказано неправильно, параметр буде тихо проігноровано (віджет повернеться до значення за замовчуванням замість викидання помилки).
Зібрати повний пакет Viewer
Повна сторінка переглядача встановлює наступні частини разом:
| Частина пакету | Вимога | Як підключено |
|---|---|---|
Ресурси переглядача, монтування та objViewer | Обов’язково | Основний рендерер документу |
| Панель інструментів переглядача | Обов’язково для повної сторінки | Розмітка хоста; кнопки викликають той самий objViewer |
| Панель пошуку | Опціональний, ліцензований модуль | doconutSearchBar(...).attach(objViewer) |
| Панель анотацій | Опціональний, ліцензований модуль | doconutAnnotationBar(...).attach(objViewer) |
Хоча основна панель інструментів Viewer є розміткою хоста, вона встановлюється разом з Viewer і ніколи не повинна документуватись як окремий елемент керування. Це зберігає її розташування, мітки, іконки та правила авторизації під контролем вашого застосунку, тоді як кожна кнопка керує тим самим екземпляром Viewer:
<nav id="toolbar" aria-label="Document viewer controls">
<button type="button" onclick="objViewer.GotoPage(1)">First</button>
<button type="button" onclick="objViewer.Next(false)">Previous</button>
<button type="button" onclick="objViewer.Next(true)">Next</button>
<button type="button" onclick="objViewer.GotoPage(objViewer.TotalPages())">Last</button>
<button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
<button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
<button type="button" onclick="objViewer.FitType('width')">Fit width</button>
<button type="button" onclick="objViewer.FitType('height')">Fit height</button>
<button type="button" id="openSearch">Search</button>
<button type="button" id="openAnnotations">Annotations</button>
</nav>Дотримуйтесь такого порядку ініціалізації:
- Вивести CSS для переглядача та ліцензованих модулів.
- Відобразити панель інструментів переглядача, монтування пошуку/аннотації та монтування переглядача разом.
- Вивести скрипти для переглядача та ліцензованих модулів.
- Завантажити власний скрипт‑помічник панелі інструментів хост‑додатку.
- Ініціалізувати
docViewerі зберегти отриманийobjViewer. - Ініціалізувати кожну ліцензовану панель пошуку або анотації.
- Викликати
attach(objViewer)на кожній панелі. - Відкрити документ і зберегти його токен для запитів Viewer та модулів.
Охорони на боці сервера важливі: коли опціональна можливість недоступна, її скрипт не виводиться, тому функція jQuery‑плагіна не існує.
<script>
let token = '';
const refitViewer = () =>
requestAnimationFrame(() => objViewer.Refit());
@if (Viewer.IsSearchEnabled)
{
<text>
searchBar = $('#searchBarMount').doconutSearchBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token }),
onLayout: refitViewer
});
searchBar.attach(objViewer);
</text>
}
@if (Viewer.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token }),
onLayout: refitViewer
});
annBar.attach(objViewer);
</text>
}
document.getElementById('openSearch').addEventListener('click', () => {
if (!searchBar) return;
searchBar.isOpen() ? searchBar.close() : searchBar.open();
});
document.getElementById('openAnnotations').addEventListener('click', () => {
if (!annBar) return;
annBar.isOpen() ? annBar.close() : annBar.open();
});
</script>Обидва вбудовані компоненти генерують власний DOM панелі. Пошук містить групи «Знайти», «Параметри» та «Результати». Анотація містить інструменти створення, керування стилем, дії збереження та опціональні дії експорту/зображення. Панелі відкривають open(), close(), reset() та isOpen(); завжди викликайте attach(objViewer) один раз після їх створення.
У наведеному вище прикладі пропущено опціональні зворотні виклики хоста та кінцеві точки експорту/зображення анотацій, щоб мінімізувати запуск. Дивіться Пошук і Анотації для повної налаштування функціоналу, або Власні теми для стилізації чи заміни панелі інструментів Viewer, якою керує хост.
Відкрити документ
На боці сервера є один кінцевий пункт: інжектований сервіс Viewer відкриває документ і повертає токен сесії. Відкриття є асинхронним у цьому випуску.
app.MapPost("/api/open", async (Viewer viewer) =>
{
// Токен є непрозорим — передайте його віджету, ніколи не записуйте в журнал і не зберігайте його.
string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});Клієнт отримує цей токен і передає його віджету за допомогою objViewer.View(token):
fetch('/api/open', { method: 'POST' })
.then(resp => resp.json())
.then(data => {
token = data.token;
objViewer.View(token);
});Перед першим відкриттям нічого не потрібно розігрівати. Якщо ви переносите застосунок далі, видаліть будь‑який виклик InitCache() і прапорець, що його захищає — метод більше не існує.
Закрити документ
Викличте objViewer.Close(true), коли користувач залишає переглядач або відкриває замінний документ: це очищає віджет і надсилає запит на закриття до сервера. objViewer.Close() без аргументу очищає лише віджет. У серверних робочих процесах viewer.CloseDocument(token) негайно видаляє кешовану сесію, знищує рушій рендерингу, стирає його маркер безпеки та анулює токен. Поступове закінчення терміну дії зрештою виконує те ж очищення, але явне закриття рекомендовано для великих документів.
Повний потік запитів виглядає так:
AddDoconut + middleware
-> render CSS/scripts and mount div
-> initialize docViewer
-> OpenDocumentAsync
-> return opaque token
-> objViewer.View(token)
-> page/search/annotation requests
-> Close / CloseDocumentСтавтеся до токену як до облікових даних типу bearer: ніколи не реєструйте його, ніколи не зберігайте, передавайте його лише віджету. Він ідентифікує активну сесію документа на сервері і перестає працювати, коли ця сесія закінчується — повторно відкрийте документ, щоб отримати новий.
Запустити
Розмістіть PDF за адресою wwwroot/files/Sample.pdf, запустіть dotnet run і відкрийте сторінку, що містить віджет. Перша сторінка відображається у переглядачі, з панеллю мініатюр зліва. Якщо цього не відбувається, дивіться Усунення проблем.
Що ви отримуєте без ліцензії
Відсутність ліцензії не викликає помилку. Переглядач відображається звичайно, але кожна сторінка містить водяний знак оцінки. Дивіться Налаштування ліцензії, щоб дізнатися, як Doconut знаходить ліцензію і які зміни відбуваються після цього.
Чи була ця сторінка корисною?