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, pełny pakiet Viewer (pasek narzędzi Viewer, montaż Viewer oraz opcjonalne wstążki Wyszukiwania/Adnotacji), odwołania do zasobów, inicjalizacja klienta, otwieranie dokumentu i wykonanie.
Aplikacja hosta musi celować w środowisko uruchomieniowe obsługujące netstandard2.1 — .NET Core 3.0 lub nowszy.
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 taką. 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 Doconut został już zarejestrowany 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ć zarejestrowane przed UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());Ta konfiguracja zachowuje historyczną strukturę żądania DocImage.axd i montuje middleware dokumentu na pasującej gałęzi. To układ, który należy skopiować, gdy przenosisz istniejącą aplikację .NET Standard, ponieważ klient nadal wywołuje ten sam URL, co zawsze:
builder.Services.AddDoconut(options =>
{
options.UnsafeMode = false; // pozostaw włączone sprawdzanie sesji Doconut's
options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // stan sesji wymaga pamięci podręcznej (MVC/Razor Pages już dodają jedną)
builder.Services.AddSession(options =>
{
options.IdleTimeout = TimeSpan.FromSeconds(3600);
options.Cookie.HttpOnly = true;
options.Cookie.IsEssential = true;
});
// Wymagane dla kodowań wielobajtowych w niektórych formatach dokumentów.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources(); // PRZED gałęzią dokumentu
app.MapWhen(
context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconut() nie przyjmuje żadnych opcji w tej wersji — wszystko zostało przeniesione do AddDoconut().
MiddlewarePath jest wartością koordynacyjną; nie mapuje samodzielnie gałęzi ASP.NET Core. Z gałęzią DocImage.axd powyżej, klient używa BasePath: '/'; z app.Map("/doconut", ...) z minimalnej konfiguracji, 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'.
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 Adnotacje wstrzykują swoje osadzone wstążki do opcjonalnych montażów, ale te moduły nigdy nie są samodzielne: zawsze dołączają do Viewer na tej samej stronie.
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Przyciski nawigacji podglądu, 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 tagi <link> i <script> przeglądarki w kolejności zależności — widget 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, poproś jednocześnie o zasoby Viewer i modułu:
@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 rdzenia. 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.
Te wywołania zastępują ręcznie kopiowane pliki skryptów. Jeśli aplikacja nadal ładuje własne docViewer.js, documentLinks.js lub docViewer.UI.js, usuń te tagi, gdy strona działa z wygenerowanych zasobów — zobacz przewodnik migracji.
Inicjalizacja przeglądarki
Widget 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: '/', // gałąź DocImage.axd; 'doconut' z app.Map("/doconut", ...)
ResPath: 'doconut-res/images',
onViewerReady: function () {
// strony są widoczne; można tutaj ukryć wskaźnik ładowania
},
// Przekaż zdarzenia cyklu życia adnotacji do osadzonej wstążki, gdy jest obecna.
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});Cztery szczegóły decydują, czy ta strona w ogóle działa:
- Wywołania zwrotne są opcjami.
onViewerReady,onViewerBusy,onCopyionAutoLoadStatussą przekazywane w obiekcie opcji. Poprzedni viewer wyprowadzał nazwy globalnych funkcji z identyfikatora kontenera i wywoływał je; ten nie robi tego. Obsługa zadeklarowana wyłącznie jako globalna funkcja nigdy nie zostaje uruchomiona i nic nie jest zgłaszane. ResPathwskazuje na prefiks zasobów, a nie na korzeń aplikacji. Przy domyślnymResourcesPath, ta wartość todoconut-res/images. Jeśli zmieniłeśResourcesPath, użyj własnego prefiksu. Ikony znajdują się w folderze o jeden poziom niżej niż korzeń zasobów: przy'doconut-res', każda ikona zwraca 404, podczas gdy sam dokument nadal się renderuje.BasePathnie ma wiodącego ukośnika oprócz wartości korzenia witryny'/'.'doconut'żąda/doconut/DocImage.axd;'/doconut'generuje//doconut/DocImage.axd, które przeglądarka interpretuje jako żądanie do innego hosta.- Zachowaj viewer, 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.
Wszystkie te błędy są ciche — zobacz Rozwiązywanie problemów oraz przewodnik migracji.
Zapisy opcji są naprawdę mieszane — showThumbs, autoLoad i pageZoom są w stylu camelCase, ale FitType, BasePath i ResPath są w stylu PascalCase. Nie ma spójnej reguły; błędne użycie wielkości liter powoduje, że opcja jest cicho ignorowana (widget przełącza się na domyślne zamiast zgłosić błąd).
Zbuduj kompletny pakiet Viewer
Pełna strona przeglądarki instaluje następujące elementy razem:
| Część pakietu | Wymaganie | Jak jest podłą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 Search | Opcjonalny, licencjonowany moduł | doconutSearchBar(...).attach(objViewer) |
| Wstążka Annotation | Opcjonalny, licencjonowany moduł | doconutAnnotationBar(...).attach(objViewer) |
Chociaż główny pasek narzędzi Viewer jest markupem hosta, jest instalowany razem z Viewerem i nigdy nie powinien być dokumentowany jako odrębny kontroler. Zapewnia to, że jego układ, etykiety, ikony i reguły autoryzacji pozostają 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>Zachowaj następującą kolejność inicjalizacji:
- Wygeneruj CSS dla Viewer i licencjonowanych modułów.
- Wyrenderuj pasek narzędzi Viewer, montowanie Search/Annotation oraz montowanie Viewer razem.
- Wygeneruj skrypty dla Viewer i licencjonowanych modułów.
- Załaduj własny skrypt pomocniczy paska narzędzi aplikacji hosta.
- Zainicjuj
docVieweri zachowaj wynikowyobjViewer. - Zainicjuj każdy licencjonowany pasek Search lub Annotation.
- Wywołaj
attach(objViewer)na każdym pasku. - Otwórz dokument i zachowaj jego token do żądań Viewer i modułów.
Zabezpieczenia 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 paska Ribbon. Search zawiera grupy Znajdź, Opcje i Wyniki. Annotation zawiera narzędzia autorskie, 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.
Powyższy przykład pomija opcjonalne wywołania zwrotne hosta oraz punkty końcowe eksportu/obrazu Annotation, aby zminimalizować uruchamianie. Zobacz Search i Annotations aby uzyskać pełną konfigurację specyficzną dla funkcji, lub Custom Themes, aby stylizować lub zastąpić pasek narzędzi Viewer będący własnością hosta.
Otwórz dokument
Po stronie serwera jest jeden punkt końcowy: wstrzyknięta usługa Viewer otwiera dokument i zwraca token sesji. Otwieranie jest asynchroniczne w tej wersji.
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);
});Nie ma nic do wstępnego przygotowania przed pierwszym otwarciem. Jeśli przenosisz aplikację dalej, usuń każde wywołanie InitCache() oraz flagę go chroniącą — metoda już nie istnieje.
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ść, 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ę, na której znajduje się 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 Konfiguracja licencji, aby dowiedzieć się, jak Doconut znajduje licencję i co się zmienia, gdy ją znajdzie.
Czy ta strona była pomocna?