Швидкий старт
Відобразіть свій перший документ за кілька хвилин
Цей посібник переводить додаток ASP.NET Core з порожнього Program.cs до документа, відображеного в браузері: реєстрація сервера, повний пакет Viewer (панель інструментів Viewer, монтування Viewer та додаткові стрічки пошуку/анотації), посилання на ресурси, ініціалізація клієнта, відкриття документа та виконання.
Налаштування сервера
AddDoconut() реєструє сервіси; UseDoconutResources() і UseDoconut() підключають проміжне ПЗ. Виклик ресурсів має бути першим. 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());Для розташування шляхів у продакшн‑стилі, прив'яжіть проміжне ПЗ документа до явної гілки та збережіть узгодженість чотирьох налаштувань шляхів:
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 як одну композицію сторінки. Пошук і Анотація вставляють свої вбудовані стрічки в необов'язкові монтування, проте ці модулі ніколи не працюють окремо: вони завжди приєднуються до 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 — це обов'язкові базові прапорці. Ніколи не публікуйте приклад стрічки Пошуку або Анотації без них, монтування 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 () {
// сторінки видимі; безпечно сховати індикатор завантаження тут
},
// Перенаправляти події життєвого циклу анотації до вбудованої ribbon, коли вона присутня.
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Ставтеся до токену як до облікових даних носія: ніколи не журналюйте його, не зберігайте, передавайте його лише віджету. Він ідентифікує активну сесію документа на сервері і перестає працювати, коли ця сесія закінчується — відкрийте документ знову, щоб отримати новий.
Запустити
Помістіть PDF у wwwroot/files/Sample.pdf, запустіть dotnet run і відкрийте сторінку, що містить віджет. Перша сторінка відображається у переглядачі, з панеллю мініатюр ліворуч. Якщо цього не відбувається, дивіться Усунення проблем.
Що ви отримуєте без ліцензії
Відсутність ліцензії не викликає помилок. Переглядач працює нормально, але кожна сторінка містить водяний знак оцінки. Дивіться Налаштування ліцензії, щоб дізнатися, як Doconut знаходить ліцензію і що змінюється після її отримання.
Чи була ця сторінка корисною?