Быстрый старт

Отобразите ваш первый документ за несколько минут

Это руководство переводит приложение ASP.NET Core от пустого Program.cs к документу, отображаемому в браузере: регистрация сервера, полный пакет Viewer (панель инструментов Viewer, монтирование Viewer и необязательные ленты 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 во время Установка? Перейдите к следующему разделу.

csharp
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());

Для компоновки путей в стиле production, сопоставьте middleware документа с явной веткой и держите четыре настройки пути согласованными:

csharp
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 — обязательное ядро страницы. Его поверхность рендеринга использует два вложенных divs:

html
<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

Рассматривайте панель инструментов, монтирование модулей и поверхность Viewer как одну композицию страницы. Search и Annotation внедряют свои встроенные ленты в необязательные монтирования, но эти модули никогда не работают отдельно: они всегда присоединяются к Viewer на той же странице. Используйте следующий порядок:

html
<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>

Ссылка на ресурсы viewer

В Razor‑view, внедренный сервис Viewer генерирует теги <link> и <script> viewer в порядке зависимостей — виджет является плагином jQuery, поэтому jQuery должен быть загружен до скриптов viewer:

html
@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
@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 всё равно запускается.

Инициализация viewer

Клиентский виджет — это плагин jQuery. Это минимальный набор реальных параметров инициализации (не псевдокод):

javascript
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, никогда не вызывается.
  • Сохраните viewer, а затем вызывайте View отдельно. docViewer(...) возвращает объект с Zoom, Next и FitType; View(...) возвращает что‑то другое. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) отображает документ, затем падает с objViewer.Zoom is not a function при первом щелчке по панели инструментов.

Сборка полного пакета Viewer

Полная страница Viewer устанавливает следующие части вместе:

Часть пакетаТребованиеКак подключено
Ресурсы Viewer, монтирование и objViewerОбязательноОсновной рендерер документа
Панель инструментов ViewerТребуется для полной страницыРазметка хоста; кнопки вызывают тот же objViewer
Лента поискаОпциональный, лицензированный модульdoconutSearchBar(...).attach(objViewer)
Лента аннотацийОпциональный, лицензированный модульdoconutAnnotationBar(...).attach(objViewer)

Хотя основная панель инструментов Viewer является разметкой хоста, она устанавливается вместе с Viewer и никогда не должна документироваться как отдельный элемент управления. Это сохраняет её макет, подписи, иконки и правила авторизации под контролем вашего приложения, в то время как каждая кнопка управляет тем же экземпляром Viewer:

html
<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">.

Соблюдайте следующий порядок инициализации:

  1. Сгенерировать CSS для Viewer и лицензированных модулей.
  2. Отрисовать панель инструментов Viewer, монтирования поиска/аннотаций и монтирование Viewer вместе.
  3. Сгенерировать скрипты для Viewer и лицензированных модулей.
  4. Загрузить собственный вспомогательный скрипт панели инструментов приложения‑хоста.
  5. Инициализировать docViewer и сохранить полученный objViewer.
  6. Инициализировать каждую лицензированную ленту поиска или аннотаций.
  7. Вызвать attach(objViewer) для каждой ленты.
  8. Открыть документ и сохранить его токен для запросов Viewer и модулей.

В распределённом развертывании дополнительное значение запроса access и настройки повторных асинхронных рендеров относятся к транспортному уровню; они не меняют способ сборки Viewer, панели инструментов или лент.

Защита на стороне сервера важна: когда опциональная возможность недоступна, её скрипт не генерируется, поэтому её функция jQuery‑плагина не существует.

html
<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 ленты. Поиск содержит группы Find, Options и Results. Аннотации содержат инструменты создания, элементы управления стилем, действия сохранения и опциональные действия экспорта/изображения. Панели предоставляют open(), close(), reset() и isOpen(); всегда вызывайте attach(objViewer) один раз после их создания.

Приведённый выше пример опускает опциональные обратные вызовы хоста и конечные точки экспорта/изображения аннотаций, чтобы минимизировать запуск. См. Поиск и Аннотации для полной настройки функций, или Пользовательские темы для стилизации или замены панели инструментов Viewer, принадлежащей хосту.

Открыть документ

Серверная часть представляет собой одну конечную точку: внедрённый сервис Viewer открывает документ и возвращает токен сеанса.

csharp
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):

javascript
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) немедленно удаляет кэшированный сеанс, освобождает движок рендеринга, удаляет его маркер безопасности и аннулирует токен. Скользящее истечение срока действия в конечном итоге выполняет ту же очистку, но явное закрытие рекомендуется для больших документов.

Завершённый поток запросов выглядит так:

text
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 находит лицензию и какие изменения происходят после её обнаружения.

Была ли эта страница полезной?