Быстрый старт
Отобразите ваш первый документ за несколько минут
Этот пошаговый гид переводит приложение ASP.NET Core из пустого Program.cs в документ, отображаемый в браузере: регистрация сервера, полный пакет Viewer (панель инструментов Viewer, монтирование Viewer и необязательные ленты Поиска/Аннотации), ссылки на ресурсы, инициализация клиента, открытие документа и выполнение.
Настройка сервера
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'. Запишите оба без начального слеша: viewer добавляет его сам, поэтому '/doconut' превратится в //doconut/DocImage.axd, который браузер воспринимает как запрос к хосту с именем doconut, и viewer выдаёт ошибку «The viewer handler could not be reached».
Добавьте Viewer на страницу
Viewer является обязательным ядром страницы. Его поверхность рендеринга использует два вложенных div:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Рассматривайте панель инструментов, монтирования модулей и поверхность Viewer как единую композицию страницы. Поиск и Аннотация внедряют свои встроенные ленты в необязательные монтирования, но эти модули никогда не работают автономно: они всегда присоединяются к Viewer на той же странице. Используйте следующий порядок:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Кнопки навигации, масштабирования, Search и Annotation Viewer -->
</nav>
<div id="searchBarMount"></div>
<div id="annBarMount"></div>
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Ссылка на ресурсы Viewer
В Razor‑view внедренный сервис Viewer генерирует теги <link> и <script> viewer в порядке зависимостей — виджет является плагином jQuery, поэтому jQuery должен быть загружен до скриптов viewer:
@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
instance. 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) =>
{
// Токен непрозрачный — передайте его widget, никогда не логируйте и не сохраняйте его.
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 находит лицензию и какие изменения происходят после её обнаружения.
Была ли эта страница полезной?