ViewerConfig
Opcje widżetu przeglądarki klienckiej
ViewerConfig (przestrzeń nazw Doconut) opisuje wygląd i zachowanie przeglądarki widoku. Nie wpływa na jakość renderowania dokumentu; użyj konfiguracji formatu w tym celu. Klasa C# i długo istniejący widżet JavaScript mają różne wartości domyślne, więc mapuj wartości explicite.
Dwie zmiany po stronie klienta w tej wersji nie wyświetlają błędów. Funkcje obsługi są przekazywane jako opcje — widżet nie pobiera już swoich wywołań zwrotnych zdarzeń z identyfikatora kontenera — i
ResPathmusi wskazywać prefiks zasobów, a nie korzeń aplikacji. Oba pozostawiają serwer w pełni sprawnym i nie zgłaszają nic w konsoli przeglądarki. Jeśli przenosisz stronę z poprzedniej biblioteki, przeczytaj Wywołania zwrotne i Lista kontrolna ścieżek przed czymkolwiek innym.
Właściwości C#
| Typ | Właściwość | Domyślnie | Opis |
|---|---|---|---|
bool | ShowThumbs | true | Pokaż panel miniatur. |
bool | AutoLoad | false | Automatycznie ładuje po inicjalizacji. Normalny przepływ tokenów wywołuje View(token) explicite. |
bool | AutoFocus | true | Przenieś fokus/scroll przeglądarki do widoku podczas inicjalizacji. |
bool | AutoPageFocus | true | Utrzymaj bieżącą miniaturę widoczną podczas zmiany stron. |
int | PageZoom | 100 | Początkowy procent powiększenia. |
int | ZoomStep | 10 | Procent dodawany lub usuwany przez polecenia powiększenia. |
int | MaxZoom | 300 | Maksymalny procent powiększenia. |
bool | ShowToolTip | true | Pokaż podpowiedź pozycji strony podczas przewijania. |
string | ToolTipPageText | "Page " | Prefiks używany w podpowiedzi strony. |
bool | CacheEnabled | false | Zachowaj przesuwające się okno obrazów stron w pamięci przeglądarki. Nie używa localStorage. |
bool | LargeDoc | false | Dodawaj elementy stron w czasowych partiach dla dużych dokumentów. |
bool | ShowHyperlinks | false | Renderuj nakładki hiperłączy, gdy konfiguracja serwera je wyodrębni. |
bool | FixedZoom | true | Użyj stałego procentu powiększenia zamiast responsywnego przeliczania. |
int | FixedZoomPercent | 100 | Stałe powiększenie na pulpicie. |
int | FixedZoomPercentMobile | 75 | Stałe powiększenie na urządzeniach mobilnych. |
string | BasePath | "/" | Gdzie widok wysyła żądania stron. "/" jest DocImage.axd w korzeniu witryny; w przeciwnym razie gałąź, w której host mapuje UseDoconut(), bez wiodącego / ("doconut" oznacza /doconut/DocImage.axd). |
string | ResPath | "doconut-res/images" (26.9.0; "doconut-res" before) | Folder, z którego widżet ładuje własne obrazy: folder images pod ResourcesPath, bez wiodącego /. |
string | FitType | "width" | "width", "height" lub pusty, aby nie dopasowywać automatycznie. "page" nie jest akceptowany przez bieżący widżet. |
bool | RetryOn409 | false | Włącz sondowanie, gdy asynchroniczna/rozproszona produkcja stron odpowiada 202 Accepted; 409 jest również akceptowane dla zgodności ze starszymi serwerami. Nie jest potrzebne w normalnym synchronicznym widoku. |
var config = new ViewerConfig
{
ShowThumbs = true,
AutoLoad = false,
PageZoom = 100,
MaxZoom = 300,
FitType = "width",
BasePath = "doconut", // brak początkowego '/' : przeglądarka dodaje go ("/doconut" stałoby się //doconut, inny host)
ResPath = "doconut-res/images",
ShowHyperlinks = true
};Mapowanie C# na JavaScript
Nie przekazuj bezpośrednio zserializowanego ViewerConfig do docViewer(...). Większość kluczy widżetu jest w stylu camelCase, podczas gdy trzy ustalone klucze ścieżki/dopasowania są w stylu PascalCase.
| C# | JavaScript |
|---|---|
ShowThumbs | showThumbs |
AutoLoad | autoLoad |
AutoFocus | autoFocus |
AutoPageFocus | autoPageFocus |
PageZoom | pageZoom |
ZoomStep | zoomStep |
MaxZoom | maxZoom |
ShowToolTip | showToolTip |
ToolTipPageText | toolTipPageText |
CacheEnabled | cacheEnabled |
LargeDoc | largeDoc |
ShowHyperlinks | showHyperlinks |
FixedZoom | fixedZoom |
FixedZoomPercent | fixedZoomPercent |
FixedZoomPercentMobile | fixedZoomPercentMobile |
BasePath | BasePath |
ResPath | ResPath |
FitType | FitType |
RetryOn409 | retryOn409 |
Domyślne ustawienia JavaScript
Widżet ma starsze domyślne wartości, które różnią się od klasy C#. Poniższe wartości pochodzą z bieżącej implementacji docViewer.js.
| Opcja | Domyślne | Uwagi |
|---|---|---|
leftMinWidth / leftMaxWidth | 220 / 800 | Granice szerokości panelu miniatur. |
showThumbs | true | Początkowa widoczność miniatur. |
autoFocus / autoPageFocus | true / false | autoPageFocus różni się od domyślnego ustawienia C#. |
thumbWidth / thumbHeight / thumbPadding | 150 / 200 / 10 | Geometria miniatur w pikselach. |
pageZoom / zoomStep / maxZoom | 100 / 10 / 200 | JavaScript maxZoom różni się od C# (300). |
showToolTip / toolTipPageText | true / "Page " | Podpowiedź pozycji strony. |
format / doc / AccessToken | "" / 0 / "" | Wewnętrzne wartości inicjalizacji; zazwyczaj wypełniane przez View(token). |
debugMode | false | Dodatkowa diagnostyka po stronie klienta. |
FitType | "" | Brak automatycznego dopasowania, chyba że zostanie podane. |
BasePath | "DocImage.axd" | Historyczne domyślne ustawienie klienta zachowane dla kompatybilności. Aktualni hosty ASP.NET Core muszą ustawić je jawnie na mapowaną gałąź middleware. |
ResPath | "" | Ustaw jawnie ścieżkę do osadzonych obrazów. |
cacheEnabled / cacheCount / cacheDelay | false / 3 / 3 | Okno i opóźnienie wczytywania stron w pamięci. |
autoLoad | false | Zalecany jest jawny przepływ tokenów. |
largeDoc | true | Różni się od domyślnego ustawienia C#. |
fixedZoom | false | Różni się od domyślnego ustawienia C#. |
fixedZoomPercent / fixedZoomPercentMobile | 100 / 50 | Wartość mobilna różni się od C# (75). |
showHyperlinks | true | Wymaga wyodrębniania po stronie serwera w celu tworzenia nakładek. |
Ustaw wszystkie istotne pod względem zachowania wartości zamiast polegać na którejkolwiek z domyślnych konfiguracji:
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>
<script>
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
autoFocus: true,
autoPageFocus: true,
pageZoom: 100,
zoomStep: 10,
maxZoom: 300,
FitType: 'width',
cacheEnabled: false,
largeDoc: false,
showHyperlinks: true,
fixedZoom: true,
fixedZoomPercent: 100,
fixedZoomPercentMobile: 75,
BasePath: 'doconut',
ResPath: 'doconut-res/images',
onViewerReady: function () {},
onError: function (message) { console.error('DocViewer:', message); }
});
</script>Wywołania zwrotne
| Wywołanie zwrotne | Argumenty | Cel |
|---|---|---|
onPageLoading | pageNum | Rozpoczyna się żądanie strony. |
onPageLoaded | pageNum | Obraz strony zakończył ładowanie. |
onThumbnailClicked | pageNum | Użytkownik wybrał miniaturę. |
onPageClicked | pageNum | Użytkownik wybrał stronę. |
onDoubleClick | none | Podgląd otrzymał podwójne kliknięcie. |
onViewerBusy | none | Podgląd wszedł w stan zajętości. |
onViewerReady | none | Inicjalizacja zakończona. |
onViewerError | none | Podgląd wszedł w stan błędu. |
onError | message | Operacja zwróciła komunikat o błędzie. |
onCopy | data | Dostępne są dane kopiowania tekstu. |
onAutoLoadStatus | pageNum | Automatyczne ładowanie przeszło do kolejnej strony. |
onThumbsShown | none | Panel miniatur stał się widoczny. |
onAnnLoaded | none | Dane adnotacji załadowane. |
onAnnSaved | none | Dane adnotacji zapisane. |
onAnnSaveError | none | Zapis adnotacji nie powiódł się. |
onAnnClosed | none | Interfejs adnotacji zamknięty. |
Utrzymuj wywołania zwrotne szybkie; wysyłaj telemetrykę asynchronicznie i nie blokuj renderowania strony.
Każde z nich jest opcją w obiekcie init. Poprzedni podgląd wyszukiwał globalne funkcje, których nazwy były wyprowadzane z identyfikatora kontenera — strona z <div id="div_ctlDoc"> musiała jedynie zadeklarować function ctlDoc_OnViewerReady(). To wyszukiwanie już nie istnieje. Przekaż funkcję jawnie:
function ctlDoc_OnViewerBusy() { /* pokaż swój wskaźnik zajętości */ }
function ctlDoc_OnViewerReady() { /* ukryj go */ }
function ctlDoc_Copy(text) { /* użyj skopiowanego tekstu */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* raportuj postęp */ }
const objViewer = $('#div_ctlDoc').docViewer({
// ... twoje istniejące opcje ...
onViewerBusy: ctlDoc_OnViewerBusy, // został znaleziony po nazwie
onViewerReady: ctlDoc_OnViewerReady, // został znaleziony po nazwie
onCopy: ctlDoc_Copy, // was ctlDoc_Copy(text)
onAutoLoadStatus: ctlDoc_AutoLoadStatus // was ctlDoc_AutoLoadStatus(page)
});Stare wyszukiwanie było opakowane w pusty catch, więc nic nie było zgłaszane. W tej wersji funkcje po prostu nigdy się nie wykonują: typowym objawem jest nieustannie obracający się wskaźnik zajętości, który nigdy nie zatrzymuje się, ponieważ obsługa, która go ukrywała, była onViewerReady. Dokument za nim renderuje się poprawnie.
Dwa haki zapisu adnotacji nadal są wyszukiwane po nazwie: SaveAnnotations() wywołuje <elementId>_BeforeAnnSave() i <elementId>_DeletedAnnotationIds(), gdy istnieją, używając pełnego identyfikatora elementu (div_ctlDoc_BeforeAnnSave dla powyższego przykładu).
Nie ma wywołania zwrotnego przy kliknięciu linku — obsługa hiperłączy jest wbudowana i sterowana przez showHyperlinks.
Publiczne grupy metod
| Grupa | Wspólne metody |
|---|---|
| Cykl życia | View(token, accessToken?), Close(server?), Token(), Init(), IsLoaded() |
| Nawigacja | GotoPage(page), ShowPage(page, focus?), Next(next), CurrentPage(), TotalPages() |
| Powiększanie i dopasowanie | Zoom(zoomIn), CurrentZoom(), FitType(value), Refit() |
| Orientacja | Rotate(page, angle), Flip(page, flipType) |
| Miniatury | HideThumbs(hide), ThumbSize(size), ReloadThumbs(width), ScrollToThumb(thumb) |
| Wyszukiwanie | CanSearch(), Search(...), SearchMatchCount(), SearchSummary(...), GotoSearchMatch(...) |
| Adnotacje | SaveAnnotations(), GetAnnotations(), PushAnnotations(...), CloseAnnotations(...), ShowAnnotations(...) |
| Kopiowanie | Copy(...), CopyPage(pageNumber), CopyMode(enabled) |
Plik JavaScript zawiera także wewnętrzne pomocniki. Traktuj jako stabilne punkty integracji wyłącznie metody używane przez interfejs referencyjny i udokumentowane tutaj lub w przewodnikach funkcji.
Ponawianie, gdy rozproszona strona nadal się renderuje
retryOn409 zachowuje swoją historyczną nazwę. Służy do asynchronicznej produkcji stron i ponawia bieżącą odpowiedź gotowości 202 Accepted oraz starszy sygnał 409 Conflict. Gdy jest włączony, widżet odpyta z tymi domyślnymi wartościami JavaScript:
| Opcja | Domyślne |
|---|---|
retryInitialDelayMs | 250 |
retryBackoffFactor | 1.6 |
retryMaxDelayMs | 2500 |
retryMaxAttempts | 150 |
retryMaxTotalMs | 300000 |
Pozostaw to wyłączone dla normalnego jednowęzłowego podglądu. Włączenie nie może uczynić nieobsługiwanego synchronicznego renderowania asynchronicznym.
Włącz to, gdy strony są serwowane ze współdzielonego magazynu przy użyciu FirstPagePriority, gdzie późniejsze strony prawidłowo odpowiadają 202 Accepted, dopóki nie zostaną zapisane. Klient, który nie ponawia, wyświetla uszkodzone kafelki dla stron nadal renderujących — zobacz Rozproszone wdrożenia.
Lista kontrolna ścieżek
DoconutOptions.MiddlewarePathmusi opisywać gałąź, którą faktycznie mapujesz.BasePathmusi wskazywać tę gałąź, zapisaną bez wiodącego/('doconut', nie'/doconut': podgląd dodaje ukośnik, a//doconut/...jest żądaniem do innego hosta). Typowa konfiguracja zachowuje historyczny kształt żądaniaDocImage.axdna gałęziMapWheni dlatego ustawiaBasePath: '/'.DoconutOptions.ResourcesPathjest trasą wbudowanego zasobu.ResPathzazwyczaj wskazuje swój podfolderimages, bez wiodącego/—'doconut-res/images'z domyślnym prefiksem. PustyResPathbył poprawny w poprzedniej bibliotece, gdzie zasoby pochodziły z katalogu głównego aplikacji; tutaj nie jest poprawny i powoduje błąd bez komunikatu.ExtractHyperlinksmusi być włączony w konfiguracji formatu serwera, zanimshowHyperlinksbędzie mógł wyświetlić cokolwiek.
Czy ta strona była pomocna?