Szybki start
Renderuj swój pierwszy dokument w kilka minut
Ten przewodnik prowadzi aplikację ASP.NET Core od pustego Program.cs do dokumentu renderowanego w przeglądarce: rejestracja serwera, kompletny pakiet Viewer (pasek narzędzi Viewer, montaż Viewer oraz opcjonalne wstążki Search/Annotation), 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 Instalacja? Przejdź do następnej sekcji.
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 dokumentów 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:
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 serwuje osadzony pakiet pod /doconut-res, a ścieżka zasobu obrazu widżetu wynosi więc ResPath: 'doconut-res/images'. Zapisz oba bez początkowego ukośnika: przeglądarka dodaje go samodzielnie, więc '/doconut' stanie się //doconut/DocImage.axd, co przeglądarka odczytuje jako żądanie do hosta o nazwie doconut, i przeglądarka kończy z błędem "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:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Traktuj pasek narzędzi, montaż modułów i powierzchnię Viewer jako jedną kompozycję strony. Search i Annotation wstrzykują swoje osadzone wstążki do opcjonalnych montowań, ale te moduły nigdy nie są samodzielne: zawsze przyłączają się do Viewer na tej samej stronie. Użyj tej kolejności:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Przyciski nawigacji, powiększenia, wyszukiwania i 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ładowany przed skryptami przeglądarki:
@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ć kompletny pakiet Viewer, żądaj zasobów Viewer i modułów razem:
@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 Search lub Annotation Ribbon bez nich, montażu Viewer i 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. To jest minimalny zestaw rzeczywistych opcji inicjalizacji (nie pseudokod):
let searchBar = null;
let annBar = null;
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: 'doconut', // brak wiodącego '/'
ResPath: 'doconut-res/images', // brak wiodącego '/'
onViewerReady: function () {
// strony są widoczne; można bezpiecznie ukryć wskaźnik ładowania tutaj
},
// Przekaż zdarzenia cyklu życia adnotacji do osadzonej wstążki, gdy jest ona obecna.
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, ale FitType, BasePath i ResPath są 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:
BasePathnie 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 jeden 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 coBasePath.- Wywołania zwrotne są opcjami.
onViewerReady,onErrori pozostałe trafiają do obiektu przekazywanego dodocViewer(...). Globalna funkcja nazwana po przeglądarce, taka jakctlDoc_ViewerReady, nigdy nie jest wywoływana. - Zachowaj przeglądarkę, a następnie wywołaj
Viewosobno.docViewer(...)zwraca obiekt zZoom,NextiFitType;View(...)zwraca coś innego.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)renderuje dokument, a potem niepowodzenie zobjViewer.Zoom is not a functionprzy pierwszym kliknięciu paska narzędzi.
Zbuduj kompletny pakiet Viewer
Pełna strona przeglądarki instaluje następujące elementy razem:
| Część pakietu | Wymaganie | Jak jest połączona |
|---|---|---|
Zasoby Viewer, montowanie i objViewer | Wymagane | Rdzeniowy renderujący dokument |
| Pasek narzędzi Viewer | Wymagane dla pełnej strony | Markup hosta; przyciski wywołują ten sam objViewer |
| Wstążka wyszukiwania | Opcjonalny, licencjonowany moduł | doconutSearchBar(...).attach(objViewer) |
| Wstążka adnotacji | Opcjonalny, 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. To utrzymuje jego układ, etykiety, ikony i zasady autoryzacji pod kontrolą Twojej aplikacji, podczas gdy każdy przycisk steruje tym samym wystąpieniem 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>Pomocnicy 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 tę kolejność inicjalizacji:
- Wygeneruj CSS dla Viewer i licencjonowanych modułów.
- Renderuj pasek narzędzi Viewer, montowania wyszukiwania/annotacji oraz montowanie Viewer razem.
- Wygeneruj skrypty dla Viewer i licencjonowanych modułów.
- Załaduj własny skrypt pomocniczy paska narzędzi aplikacji hosta.
- Zainicjalizuj
docVieweri zachowaj wynikowyobjViewer. - Zainicjalizuj każdą licencjonowaną wstążkę wyszukiwania lub adnotacji.
- Wywołaj
attach(objViewer)na każdej wstążce. - 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 funkcja jest niedostępna, jej skrypt nie jest generowany, więc jej funkcja wtyczki jQuery nie istnieje.
<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. Adnotacja zawiera 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 końcowe punkty eksportu/obrazu adnotacji, aby utrzymać minimalny rozruch. 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
Po stronie serwera jest jeden punkt końcowy: wstrzyknięta usługa Viewer otwiera dokument i zwraca token sesji.
app.MapPost("/api/open", async (Viewer viewer) =>
{
// Token jest nieprzezroczysty — przekaż go do widgetu, nigdy nie loguj ani nie przechowuj go.
string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});Klient pobiera ten token i przekazuje go do widgetu przy użyciu objViewer.View(token):
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 widget i wysyła żądanie zamknięcia do serwera. objViewer.Close() bez argumentu czyści tylko widget. 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ąca się wygaśnięcie ostatecznie wykonuje tę samą czynność, ale zaleca się explicite zamknięcie przy dużych dokumentach.
Pełny przepływ żądania wygląda następująco:
AddDoconut + middleware
-> render CSS/scripts and mount div
-> initialize docViewer
-> OpenDocumentAsync
-> return opaque token
-> objViewer.View(token)
-> page/search/annotation requests
-> Close / CloseDocumentTraktuj token jak poświadczenie typu bearer: nigdy go nie loguj, nigdy nie przechowuj, przekazuj go wyłącznie widgetowi. 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ę, na której znajduje się widget. Pierwsza strona renderuje się 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 Konfiguracja licencji, aby dowiedzieć się, jak Doconut znajduje licencję i co się zmienia, gdy ją znajdzie.
Czy ta strona była pomocna?