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.
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:
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:
<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:
<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:
@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.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):
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:
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 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 następnie 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 części razem:
| Część pakietu | Wymaganie | Jak jest połączona |
|---|---|---|
Zasoby Viewer, montaż i objViewer | Wymagane | Rdzeniowy renderujący dokument |
| Pasek narzędzi Viewer | Wymagane dla pełnej strony | Markowanie 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. 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:
<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:
- Wygeneruj CSS dla Viewer i licencjonowanych modułów.
- Wyrenderuj pasek narzędzi Viewer, montowanie wyszukiwania/adnotacji 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 funkcjonalność 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. 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.
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):
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:
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 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?