ViewerConfig – Doconut Dokumentacja

ViewerConfig (namespace Doconut) opisuje wygląd i zachowanie przeglądarkowego podglądu. Nie wpływa na jakość renderowania dokumentu; użyj konfiguracji formatu w tym celu. Klasa C# oraz starsza wtyczka JavaScript mają różne wartości domyślne, więc mapuj wartości explicite.

Właściwości C#

Typ	Właściwość	Domyślne	Opis
`bool`	`ShowThumbs`	`true`	Pokaż panel miniatur.
`bool`	`AutoLoad`	`false`	Automatycznie ładowany po inicjalizacji. Normalny przepływ tokenów wywołuje `View(token)` explicite.
`bool`	`AutoFocus`	`true`	Przenieś fokus/scroll przeglądarki do podglądu 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ła.
`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 podgląd wysyła żądania stron. `"/"` jest obsługą `DocImage.axd` w korzeniu witryny. Dla aplikacji w wirtualnym katalogu użyj nazwy katalogu bez wiodącego `/` (`"myapp"` oznacza `/myapp/DocImage.axd`).
`string`	`ResPath`	`"doconut-res/images"`	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 stosować automatycznego dopasowania. `"page"` nie jest akceptowany przez bieżący widżet.
`bool`	`RetryOn409`	`false`	Ponawia żądania stron, które odpowiadają „still rendering”. `DocImage.axd` renderuje synchronicznie i nigdy nie wysyła tego sygnału; pozostaw ją `false`.

csharp

var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "/",                 // "/" = obsługa DocImage.axd w katalogu głównym witryny (Web.config)
    ResPath = "doconut-res/images", // folder obrazów pod ResourcesPath, bez początkowego '/'
    ShowHyperlinks = true
};
// Wygeneruj to za pomocą viewer.RenderViewer("viewerEl", token, config) - zobacz odniesienie do Viewer.

Emitowanie ViewerConfig przy użyciu RenderViewer

Viewer.RenderViewer(elementId, token, config) zamienia ViewerConfig w skrypt inicjalizujący widżet. Zapisuje sześć powyższych właściwości — BasePath, ResPath, ShowThumbs, AutoLoad, PageZoom i FitType — a następnie wywołuje View(token). Pozostałe właściwości nie są zapisywane: dla MaxZoom, ShowHyperlinks, ustawień powiększenia lub dowolnego wywołania zwrotnego, zainicjuj widżet samodzielnie przy użyciu poniższych opcji JavaScript. Zobacz Podgląd dla RenderViewer.

Mapowanie C# na JavaScript

Nie przekazuj bezpośrednio serializowanego ViewerConfig do docViewer(...). Większość kluczy widżetu jest w stylu camelCase, podczas gdy trzy ustalone klucze ścieżka/dopasowanie 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 wartości domyślne, 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"`	Domyślne ustawienie starszej wersji. Ustaw je jawnie: `'/'` dla obsługi w katalogu głównym witryny.
`ResPath`	`""`	Ustaw jawnie ścieżkę do osadzonych obrazów.
`cacheEnabled` / `cacheCount` / `cacheDelay`	`false` / `3` / `3`	Okno i opóźnienie wstępnego ładowania 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 ekstrakcji po stronie serwera w celu tworzenia nakładek.

Ustaw wszystkie wartości istotne pod względem zachowania, 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: '/',
    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`	Dane kopiowania tekstu są dostępne.
`onAutoLoadStatus`	`pageNum`	Automatyczne ładowanie przeszło do 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.

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()`
Zoom 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 również wewnętrzne pomocnicze funkcje. Traktuj jako stabilne punkty integracji wyłącznie metody używane przez interfejs referencyjny i udokumentowane tutaj lub w przewodnikach funkcji.

Opcje ponawiania

Widżet akceptuje również retryOn409 i jego ustawienia opóźnień (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs). Służą one wdrożeniom, których strony są generowane w tle. DocImage.axd renderuje każdą stronę podczas żądania, więc pozostaw retryOn409 wyłączone.

Lista kontrolna ścieżek

BasePath jest '/', gdy obsługa DocImage.axd znajduje się w katalogu głównym witryny — atrybut path obsługi w Web.config decyduje, gdzie odpowiada. W wirtualnym katalogu użyj nazwy katalogu bez wiodącego / ('myapp', nie '/myapp': przeglądarka dodaje ukośnik, a //myapp/... to żądanie do innego hosta).
DoconutOptions.ResourcesPath to miejsce, w którym moduł zasobów udostępnia osadzone pliki (/doconut-res domyślnie).
ResPath wskazuje na jego podfolder images, również bez wiodącego / ('doconut-res/images'). Skierowanie go na 'doconut-res' powoduje, że wszystkie ikony zwracają 404, podczas gdy dokument nadal się renderuje.
W MVC, routes.IgnoreRoute("doconut-res/{*pathInfo}") musi następować po ResourcesPath, jeśli go zmienisz.
ExtractHyperlinks musi być włączone w konfiguracji formatu serwera, zanim showHyperlinks będzie w stanie wyświetlić cokolwiek.