Швидкий старт
Відобразіть свій перший документ за кілька хвилин
Цей посібник переводить додаток ASP.NET Core від порожнього Program.cs до документа, відображеного в браузері: реєстрація сервера, повний пакет Viewer (Viewer toolbar, Viewer mount, і необов’язкові стрічки Search/Annotation), посилання на ресурси, ініціалізація клієнта, відкриття документа та виконання.
Налаштування сервера
AddDoconut() реєструє сервіси; UseDoconutResources() та UseDoconut() підключають middleware. Виклик ресурсів має бути першим. UseDoconut() відповідає на кожен запит, що до нього надходить, тому змонтуйте його у власній гілці за допомогою app.Map. Виклики сесії також потрібні — стандартна безпека документів Doconut перевіряє кожен запит сторінки проти стану сесії ASP.NET. Стан сесії потребує кешу: AddDistributedMemoryCache() його надає. Додаток MVC або Razor Pages вже реєструє його, але мінімальний API‑додаток — ні, і без нього додаток зупиняється під час запуску з Unable to resolve service for type 'IDistributedCache'. Вже зареєстровано Doconut під час Встановлення? Перейдіть до наступного розділу.
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());Для розташування шляхів у продакшн‑стилі, прив’яжіть middleware документу до явної гілки та збережіть узгодженість чотирьох налаштувань шляхів:
builder.Services.AddDoconut(options =>
{
options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
options.MiddlewarePath = "/doconut";
options.ResourcesPath = "/doconut-res";
options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());MiddlewarePath — це значення координації; воно саме по собі не прив’язує гілку ASP.NET Core. У цьому прикладі хост прив’язує /doconut, тому клієнт використовує BasePath: 'doconut'. ResourcesPath подає вбудований пакет за адресою /doconut-res, а шлях до ресурсів зображень віджету відповідно ResPath: 'doconut-res/images'. Запишіть обидва без початкового слешу: переглядач додає його сам, тому '/doconut' стане //doconut/DocImage.axd, що браузер сприймає як запит до хоста з назвою doconut, і переглядач завершує роботу з помилкою "The viewer handler could not be reached".
Додати переглядач на сторінку
Viewer є необхідним ядром сторінки. Його поверхня рендерингу використовує два вкладені div:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Розглядайте панель інструментів, монтування модулів та поверхню Viewer як одну композицію сторінки.
Search та
Annotation вбудовують свої стрічки у необов’язкові монтування, проте ці модулі ніколи
не працюють окремо: вони завжди підключаються до Viewer на тій самій сторінці. Використайте такий порядок:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Кнопки навігації, масштабування, пошуку та анотацій у Viewer -->
</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 все одно запускається.
Ініціалізувати переглядач
Віджет на боці клієнта — це jQuery плагін. Це мінімальний набір реальних параметрів ініціалізації (не псевдокод):
let searchBar = null;
let annBar = null;
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: '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);
}
});Регістр параметрів дійсно змішаний — showThumbs, autoLoad і pageZoom записані у camelCase, а FitType, BasePath і ResPath — у PascalCase. Немає послідовного правила; якщо регістр вказано неправильно, параметр буде тихо проігноровано (віджет повернеться до значення за замовчуванням замість викидання помилки).
Ще чотири деталі не працюють без повідомлення про помилку:
BasePathне має початкового слешу.'doconut'запитує/doconut/DocImage.axd;'/doconut'генерує//doconut/DocImage.axd, який браузер сприймає як запит до іншого хоста.ResPath: 'doconut-res/images'— іконки розташовані на одну папку нижче кореня ресурсів. При використанні'doconut-res'кожна іконка повертає 404: немає гліфів панелі інструментів і індикатора завантаження, хоча сам документ все ще відображається. Початковий слеш руйнує це так само, якBasePath.- Зворотні виклики — це параметри.
onViewerReady,onErrorта інші передаються в об’єкт, який передається доdocViewer(...). Глобальна функція, назва якої відповідає переглядачу, наприкладctlDoc_ViewerReady, ніколи не викликається. - Залишайте переглядач, а потім викликайте
Viewокремо.docViewer(...)повертає об’єкт зZoom,NextіFitType;View(...)повертає інше.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)відображає документ, а потім падає зobjViewer.Zoom is not a functionпри першому кліку на панель інструментів.
Зібрати повний пакет Viewer
Повна сторінка переглядача встановлює наступні частини разом:
| Частина пакету | Вимога | Як підключено |
|---|---|---|
Ресурси Viewer, монтування та objViewer | Обов’язково | Ядро рендерера документу |
| Панель інструментів Viewer | Обов’язково для повної сторінки | Розмітка хоста; кнопки викликають той самий 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>Допоміжні функції обертання, мініатюр, друку, повноекранного режиму, макету та стану кнопок повинні бути у вашому власному скрипті панелі інструментів, який викликає той самий objViewer. Завантажте його після Viewer.ReferenceScripts(...) і тримайте разом з його <nav id="toolbar"> розміткою.
Дотримуйтесь цього порядку ініціалізації:
- Виведіть CSS для Viewer та ліцензованих модулів.
- Відрендерте панель інструментів Viewer, монтування Search/Annotation та монтування Viewer разом.
- Виведіть скрипти для Viewer та ліцензованих модулів.
- Завантажте власний скрипт‑помічник панелі інструментів хост‑застосунку.
- Ініціалізуйте
docViewerі збережіть отриманийobjViewer. - Ініціалізуйте кожну ліцензовану стрічку Search або Annotation.
- Викличте
attach(objViewer)на кожній стрічці. - Відкрийте документ і збережіть його токен для запитів Viewer та модулів.
У розподіленому розгортанні додаткове значення запиту access та налаштування повторних асинхронних рендерів належать до транспорту; вони не змінюють спосіб складання 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 стрічки. Search містить групи Find, Options та Results. Annotation містить інструменти створення, елементи керування стилем, дії збереження та необов’язкові дії експорту/зображення. Барі надають open(), close(), reset() і isOpen(); завжди викликайте attach(objViewer) один раз після їх створення.
У наведеному вище прикладі пропущено необов’язкові зворотні виклики хоста та кінцеві точки експорту/зображення Annotation, щоб мінімізувати запуск. Дивіться Search та Annotations для повної налаштування функцій, або Custom Themes для стилізації або заміни панелі інструментів 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);
});Закрити документ
Викличте 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 знаходить ліцензію і що змінюється після її отримання.
Чи була ця сторінка корисною?