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 ResPath musi 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#

TypWłaściwośćDomyślnieOpis
boolShowThumbstruePokaż panel miniatur.
boolAutoLoadfalseAutomatycznie ładuje po inicjalizacji. Normalny przepływ tokenów wywołuje View(token) explicite.
boolAutoFocustruePrzenieś fokus/scroll przeglądarki do widoku podczas inicjalizacji.
boolAutoPageFocustrueUtrzymaj bieżącą miniaturę widoczną podczas zmiany stron.
intPageZoom100Początkowy procent powiększenia.
intZoomStep10Procent dodawany lub usuwany przez polecenia powiększenia.
intMaxZoom300Maksymalny procent powiększenia.
boolShowToolTiptruePokaż podpowiedź pozycji strony podczas przewijania.
stringToolTipPageText"Page "Prefiks używany w podpowiedzi strony.
boolCacheEnabledfalseZachowaj przesuwające się okno obrazów stron w pamięci przeglądarki. Nie używa localStorage.
boolLargeDocfalseDodawaj elementy stron w czasowych partiach dla dużych dokumentów.
boolShowHyperlinksfalseRenderuj nakładki hiperłączy, gdy konfiguracja serwera je wyodrębni.
boolFixedZoomtrueUżyj stałego procentu powiększenia zamiast responsywnego przeliczania.
intFixedZoomPercent100Stałe powiększenie na pulpicie.
intFixedZoomPercentMobile75Stałe powiększenie na urządzeniach mobilnych.
stringBasePath"/"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).
stringResPath"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 /.
stringFitType"width""width", "height" lub pusty, aby nie dopasowywać automatycznie. "page" nie jest akceptowany przez bieżący widżet.
boolRetryOn409falseWłą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.
csharp
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
ShowThumbsshowThumbs
AutoLoadautoLoad
AutoFocusautoFocus
AutoPageFocusautoPageFocus
PageZoompageZoom
ZoomStepzoomStep
MaxZoommaxZoom
ShowToolTipshowToolTip
ToolTipPageTexttoolTipPageText
CacheEnabledcacheEnabled
LargeDoclargeDoc
ShowHyperlinksshowHyperlinks
FixedZoomfixedZoom
FixedZoomPercentfixedZoomPercent
FixedZoomPercentMobilefixedZoomPercentMobile
BasePathBasePath
ResPathResPath
FitTypeFitType
RetryOn409retryOn409

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.

OpcjaDomyślneUwagi
leftMinWidth / leftMaxWidth220 / 800Granice szerokości panelu miniatur.
showThumbstruePoczątkowa widoczność miniatur.
autoFocus / autoPageFocustrue / falseautoPageFocus różni się od domyślnego ustawienia C#.
thumbWidth / thumbHeight / thumbPadding150 / 200 / 10Geometria miniatur w pikselach.
pageZoom / zoomStep / maxZoom100 / 10 / 200JavaScript maxZoom różni się od C# (300).
showToolTip / toolTipPageTexttrue / "Page "Podpowiedź pozycji strony.
format / doc / AccessToken"" / 0 / ""Wewnętrzne wartości inicjalizacji; zazwyczaj wypełniane przez View(token).
debugModefalseDodatkowa 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 / cacheDelayfalse / 3 / 3Okno i opóźnienie wczytywania stron w pamięci.
autoLoadfalseZalecany jest jawny przepływ tokenów.
largeDoctrueRóżni się od domyślnego ustawienia C#.
fixedZoomfalseRóżni się od domyślnego ustawienia C#.
fixedZoomPercent / fixedZoomPercentMobile100 / 50Wartość mobilna różni się od C# (75).
showHyperlinkstrueWymaga 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:

html
<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 zwrotneArgumentyCel
onPageLoadingpageNumRozpoczyna się żądanie strony.
onPageLoadedpageNumObraz strony zakończył ładowanie.
onThumbnailClickedpageNumUżytkownik wybrał miniaturę.
onPageClickedpageNumUżytkownik wybrał stronę.
onDoubleClicknonePodgląd otrzymał podwójne kliknięcie.
onViewerBusynonePodgląd wszedł w stan zajętości.
onViewerReadynoneInicjalizacja zakończona.
onViewerErrornonePodgląd wszedł w stan błędu.
onErrormessageOperacja zwróciła komunikat o błędzie.
onCopydataDostępne są dane kopiowania tekstu.
onAutoLoadStatuspageNumAutomatyczne ładowanie przeszło do kolejnej strony.
onThumbsShownnonePanel miniatur stał się widoczny.
onAnnLoadednoneDane adnotacji załadowane.
onAnnSavednoneDane adnotacji zapisane.
onAnnSaveErrornoneZapis adnotacji nie powiódł się.
onAnnClosednoneInterfejs 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:

javascript
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

GrupaWspólne metody
Cykl życiaView(token, accessToken?), Close(server?), Token(), Init(), IsLoaded()
NawigacjaGotoPage(page), ShowPage(page, focus?), Next(next), CurrentPage(), TotalPages()
Powiększanie i dopasowanieZoom(zoomIn), CurrentZoom(), FitType(value), Refit()
OrientacjaRotate(page, angle), Flip(page, flipType)
MiniaturyHideThumbs(hide), ThumbSize(size), ReloadThumbs(width), ScrollToThumb(thumb)
WyszukiwanieCanSearch(), Search(...), SearchMatchCount(), SearchSummary(...), GotoSearchMatch(...)
AdnotacjeSaveAnnotations(), GetAnnotations(), PushAnnotations(...), CloseAnnotations(...), ShowAnnotations(...)
KopiowanieCopy(...), 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:

OpcjaDomyślne
retryInitialDelayMs250
retryBackoffFactor1.6
retryMaxDelayMs2500
retryMaxAttempts150
retryMaxTotalMs300000

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.MiddlewarePath musi opisywać gałąź, którą faktycznie mapujesz.
  • BasePath musi 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 żądania DocImage.axd na gałęzi MapWhen i dlatego ustawia BasePath: '/'.
  • DoconutOptions.ResourcesPath jest trasą wbudowanego zasobu.
  • ResPath zazwyczaj wskazuje swój podfolder images, bez wiodącego / — 'doconut-res/images' z domyślnym prefiksem. Pusty ResPath był poprawny w poprzedniej bibliotece, gdzie zasoby pochodziły z katalogu głównego aplikacji; tutaj nie jest poprawny i powoduje błąd bez komunikatu.
  • ExtractHyperlinks musi być włączony w konfiguracji formatu serwera, zanim showHyperlinks będzie mógł wyświetlić cokolwiek.

Czy ta strona była pomocna?