Szybki start

Renderuj swój pierwszy dokument w kilka minut

Ten przewodnik przenosi aplikację ASP.NET Core z pustego Program.cs do dokumentu renderowanego w przeglądarce: rejestracja serwera, pełny pakiet Viewer (pasek narzędzi Viewer, montaż Viewer oraz opcjonalne wstążki wyszukiwania/annotacji), odwołania do zasobów, inicjalizacja klienta, otwieranie dokumentu i wykonanie.

Konfiguracja serwera

AddDoconut() rejestruje usługi; UseDoconutResources() i UseDoconut() podłączają middleware. Wywołanie zasobów musi być pierwsze. UseDoconut() odpowiada na każde żądanie, które do niego dotrze, więc zamontuj je na własnej gałęzi przy użyciu app.Map. Wywołania sesji są również wymagane — domyślne zabezpieczenie dokumentu Doconut weryfikuje każde żądanie strony względem stanu sesji ASP.NET. Stan sesji wymaga pamięci podręcznej: AddDistributedMemoryCache() zapewnia jedną. Aplikacja MVC lub Razor Pages już ją rejestruje, ale aplikacja minimal-API nie, i bez niej aplikacja zatrzymuje się przy uruchamianiu z Unable to resolve service for type 'IDistributedCache'. Czy już zarejestrowałeś Doconut podczas Instalacji? Przejdź do następnej sekcji.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // stan sesji wymaga pamięci podręcznej (MVC/Razor Pages już dodają jedną)
builder.Services.AddSession(); // Bezpieczeństwo dokumentu Doconut opiera się na stanie sesji ASP.NET

app.UseSession();          // wywołaj UseSession() przed UseDoconut()
app.UseDoconutResources(); // musi być zarejestrowany przed UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

Dla układu ścieżek w stylu produkcyjnym, mapuj middleware dokumentu na wyraźną gałąź i utrzymaj cztery ustawienia ścieżek wyrównane:

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 jest wartością koordynacyjną; nie mapuje ona gałęzi ASP.NET Core samodzielnie. W tym przykładzie host mapuje /doconut, więc klient używa BasePath: 'doconut'. ResourcesPath udostępnia osadzony pakiet pod /doconut-res, a ścieżka zasobu obrazu widżetu jest więc ResPath: 'doconut-res/images'. Zapisz oba bez wiodącego ukośnika: przeglądarka dodaje go samodzielnie, więc '/doconut' stałoby się //doconut/DocImage.axd, co przeglądarka odczytuje jako żądanie do hosta o nazwie doconut, i przeglądarka kończy działanie z komunikatem "The viewer handler could not be reached".

Dodaj przeglądarkę do strony

Viewer jest wymaganą podstawą strony. Jego powierzchnia renderowania używa dwóch zagnieżdżonych div:

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

Traktuj pasek narzędzi, montaż modułów i powierzchnię Viewer jako jedną kompozycję strony. Wyszukiwanie i Annotacja wstrzykują swoje osadzone wstążki do opcjonalnych montażów, ale te moduły nigdy nie są samodzielne: zawsze przyłączają się do Viewer na tej samej stronie. Użyj tej kolejności:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Nawigacja Viewer, przybliżanie, wyszukiwanie i przyciski adnotacji -->
</nav>

<div id="searchBarMount"></div>
<div id="annBarMount"></div>

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

Odwołanie do zasobów przeglądarki

W widoku Razor, wstrzyknięta usługa Viewer generuje znaczniki <link> i <script> przeglądarki w kolejności zależności — widżet jest wtyczką jQuery, więc jQuery musi być załadowane przed skryptami przeglądarki:

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
}))

Aby uzyskać pełny pakiet Viewer, żądaj zasobów Viewer i modułów razem:

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 i IncludeViewerScripts są obowiązkowymi flagami podstawowymi. Nigdy nie publikuj przykładu wstążki Wyszukiwania lub Annotacji bez nich, montażu Viewer oraz instancji docViewer. ReferenceCss i ReferenceScripts pomijają zasoby opcjonalnego modułu, gdy bieżąca licencja nie przyznaje tej możliwości; podstawowy Viewer nadal się uruchamia.

Inicjalizacja przeglądarki

Widżet po stronie klienta jest wtyczką jQuery. Oto minimalny zestaw rzeczywistych opcji inicjalizacji (nie pseudokod):

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   'doconut',             // brak początkowego '/'
    ResPath:    'doconut-res/images',  // brak początkowego '/'
    onViewerReady: function () {
        // strony są widoczne; można tutaj ukryć spinner ładowania
    },
    // Przekaż zdarzenia cyklu życia adnotacji do osadzonego ribbon, gdy jest on obecny.
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Wielkość liter w opcjach jest naprawdę mieszana — showThumbs, autoLoad i pageZoom są w stylu camelCase, natomiast FitType, BasePath i ResPath w stylu PascalCase. Nie ma spójnej reguły; jeśli popełnisz błąd w wielkości liter, opcja zostanie cicho zignorowana (widżet powróci do wartości domyślnej zamiast zgłosić błąd).

Cztery kolejne szczegóły powodują niepowodzenie bez komunikatu o błędzie:

  • BasePath nie ma początkowego ukośnika. 'doconut' żąda /doconut/DocImage.axd; '/doconut' generuje //doconut/DocImage.axd, które przeglądarka odczytuje jako żądanie do innego hosta.
  • ResPath: 'doconut-res/images' — ikony znajdują się w folderze o poziom niżej niż korzeń zasobów. Z 'doconut-res' każda ikona zwraca 404: brak glifów paska narzędzi i brak wskaźnika ładowania, podczas gdy sam dokument nadal się renderuje. Początkowy ukośnik psuje to w ten sam sposób, co BasePath.
  • Wywołania zwrotne są opcjami. onViewerReady, onError i pozostałe trafiają do obiektu przekazywanego do docViewer(...). Globalna funkcja nazwana po przeglądarce, taka jak ctlDoc_ViewerReady, nigdy nie jest wywoływana.
  • Zachowaj przeglądarkę, a następnie wywołaj View osobno. docViewer(...) zwraca obiekt z Zoom, Next i FitType; View(...) zwraca coś innego. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) renderuje dokument, a następnie niepowodzenie z objViewer.Zoom is not a function przy pierwszym kliknięciu paska narzędzi.

Zbuduj kompletny pakiet Viewer

Pełna strona przeglądarki instaluje następujące części razem:

Część pakietuWymaganieJak jest połączona
Zasoby Viewer, montaż i objViewerWymaganeRdzeniowy renderujący dokument
Pasek narzędzi ViewerWymagane dla pełnej stronyMarkowanie hosta; przyciski wywołują ten sam objViewer
Wstążka wyszukiwaniaOpcjonalny, licencjonowany modułdoconutSearchBar(...).attach(objViewer)
Wstążka adnotacjiOpcjonalny, licencjonowany modułdoconutAnnotationBar(...).attach(objViewer)

Chociaż główny pasek narzędzi Viewer jest markupem hosta, jest instalowany razem z Viewer i nigdy nie powinien być dokumentowany jako odrębny kontroler. Dzięki temu jego układ, etykiety, ikony i reguły autoryzacji pozostają pod kontrolą Twojej aplikacji, podczas gdy każdy przycisk steruje tą samą instancją 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>

Pomocnicy do obrotu, miniatur, drukowania, pełnego ekranu, układu i stanu przycisków powinny znajdować się w Twoim własnym skrypcie paska narzędzi, który wywołuje ten sam objViewer. Załaduj go po Viewer.ReferenceScripts(...) i trzymaj razem z jego <nav id="toolbar"> markupem.

Zachowaj następującą kolejność inicjalizacji:

  1. Wygeneruj CSS dla Viewer i licencjonowanych modułów.
  2. Wyrenderuj pasek narzędzi Viewer, montowanie wyszukiwania/adnotacji oraz montowanie Viewer razem.
  3. Wygeneruj skrypty dla Viewer i licencjonowanych modułów.
  4. Załaduj własny skrypt pomocniczy paska narzędzi aplikacji hosta.
  5. Zainicjalizuj docViewer i zachowaj wynikowy objViewer.
  6. Zainicjalizuj każdą licencjonowaną wstążkę wyszukiwania lub adnotacji.
  7. Wywołaj attach(objViewer) na każdej wstążce.
  8. Otwórz dokument i zachowaj jego token dla żądań Viewer i modułów.

W rozproszonym wdrożeniu dodatkowa wartość żądania access oraz ustawienia ponownych prób asynchronicznego renderowania należą do transportu; nie zmieniają one sposobu, w jaki Viewer, pasek narzędzi lub wstążki są składane.

Ochrony po stronie serwera są ważne: gdy opcjonalna funkcjonalność jest niedostępna, jej skrypt nie jest generowany, więc jej funkcja wtyczki jQuery nie istnieje.

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>

Oba osadzone komponenty generują własny DOM wstążki. Wyszukiwanie zawiera grupy Znajdź, Opcje i Wyniki. Adnotacje zawierają narzędzia do tworzenia, kontrolki stylu, akcje zapisu oraz opcjonalne akcje eksportu/obrazu. Paski udostępniają open(), close(), reset() i isOpen(); zawsze wywołaj attach(objViewer) raz po ich utworzeniu.

Przykład powyżej pomija opcjonalne wywołania zwrotne hosta oraz endpointy eksportu/obrazu w Adnotacjach, aby zminimalizować uruchamianie. Zobacz Wyszukiwanie i Adnotacje dla pełnej konfiguracji specyficznej dla funkcji, lub Niestandardowe motywy, aby stylizować lub zastąpić pasek narzędzi Viewer zarządzany przez hosta.

Otwórz dokument

Strona serwera ma jeden punkt końcowy: wstrzyknięta usługa Viewer otwiera dokument i zwraca token sesji.

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // Token jest nieprzezroczysty — przekaż go do widgetu, nigdy go nie loguj ani nie przechowuj.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Klient pobiera ten token i przekazuje go do widżetu przy użyciu objViewer.View(token):

javascript
fetch('/api/open', { method: 'POST' })
    .then(resp => resp.json())
    .then(data => {
        token = data.token;
        objViewer.View(token);
    });

Zamknij dokument

Wywołaj objViewer.Close(true), gdy użytkownik opuszcza przeglądarkę lub otwiera zastępczy dokument: usuwa on widżet i wysyła żądanie zamknięcia do serwera. objViewer.Close() bez argumentu czyści tylko widżet. W przepływach sterowanych przez serwer, viewer.CloseDocument(token) natychmiast usuwa buforowaną sesję, zwalnia silnik renderujący, usuwa jego znacznik bezpieczeństwa i unieważnia token. Przesuwające się wygaśnięcie ostatecznie wykonuje tę samą czynność czyszczenia, ale zaleca się jawne zamknięcie przy dużych dokumentach.

Pełny przepływ żądania wygląda następująco:

text
AddDoconut + middleware
    -> render CSS/scripts and mount div
    -> initialize docViewer
    -> OpenDocumentAsync
    -> return opaque token
    -> objViewer.View(token)
    -> page/search/annotation requests
    -> Close / CloseDocument

Traktuj token jak poświadczenie typu bearer: nigdy go nie loguj, nigdy nie przechowuj, przekazuj go wyłącznie widżetowi. Identyfikuje on aktywną sesję dokumentu na serwerze i przestaje działać, gdy sesja wygaśnie — ponownie otwórz dokument, aby uzyskać nowy.

Uruchom to

Umieść plik PDF w wwwroot/files/Sample.pdf, uruchom dotnet run i otwórz stronę, która hostuje widżet. Pierwsza strona jest renderowana w przeglądarce, z panelem miniatur po lewej. Jeśli tak się nie dzieje, zobacz Rozwiązywanie problemów.

Co otrzymujesz bez licencji

Brak licencji nie powoduje błędu. Przeglądarka renderuje normalnie, ale każda strona zawiera znak wodny oceny. Zobacz Ustawienia licencji, aby dowiedzieć się, jak Doconut znajduje licencję i co się zmienia, gdy ją znajdzie.

Czy ta strona była pomocna?