ViewerConfig – Dokumentacja Doconut

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# i długo istniejący widget JavaScript mają różne wartości domyślne, więc mapuj wartości jawnie.

Właściwości C#

Typ	Właściwość	Domyślne	Opis
`bool`	`ShowThumbs`	`true`	Pokaż panel miniatur.
`bool`	`AutoLoad`	`false`	Automatycznie ładuje po inicjalizacji. Normalny przepływ tokenów wywołuje `View(token)` jawnie.
`bool`	`AutoFocus`	`true`	Przesuwa fokus/scroll przeglądarki do podglądu podczas inicjalizacji.
`bool`	`AutoPageFocus`	`true`	Utrzymuje 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`	Pokazuje podpowiedź pozycji strony podczas przewijania.
`string`	`ToolTipPageText`	`"Page "`	Prefiks używany w podpowiedzi strony.
`bool`	`CacheEnabled`	`false`	Utrzymuje przesuwające się okno obrazów stron w pamięci przeglądarki. Nie używa `localStorage`.
`bool`	`LargeDoc`	`false`	Dodaje elementy stron w czasowych partiach dla dużych dokumentów.
`bool`	`ShowHyperlinks`	`false`	Renderuje nakładki hiperłączy, gdy konfiguracja serwera je wyodrębniła.
`bool`	`FixedZoom`	`true`	Używa stałego procentu powiększenia zamiast responsywnego przeliczenia.
`int`	`FixedZoomPercent`	`100`	Stałe powiększenie na pulpicie.
`int`	`FixedZoomPercentMobile`	`75`	Stałe powiększenie na urządzeniach mobilnych.
`string`	`BasePath`	`"/"`	Gałąź, w której host mapuje `UseDoconut()`.
`string`	`ResPath`	`"doconut-res"`	Podstawowa ścieżka zasobów używana przez widget. W normalnej konfiguracji skieruj ją do `<ResourcesPath>/images`.
`string`	`FitType`	`"width"`	`"width"`, `"height"` lub pusty, aby nie stosować automatycznego dopasowania. `"page"` nie jest akceptowane przez bieżący widget.
`bool`	`RetryOn409`	`false`	Włącza odpytywanie, 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 podglądzie.

csharp

var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "/doconut",
    ResPath = "/doconut-res/images",
    ShowHyperlinks = true
};

Mapowanie C# na JavaScript

Nie przekazuj bezpośrednio zserializowanego ViewerConfig do docViewer(...). Większość kluczy widgetu 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 wartości JavaScript

Widget posiada 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ślnej wartości w C#.
`thumbWidth` / `thumbHeight` / `thumbPadding`	`150` / `200` / `10`	Geometria miniatur w pikselach.
`pageZoom` / `zoomStep` / `maxZoom`	`100` / `10` / `200`	`maxZoom` w JavaScript 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"`	Historyczna domyślna wartość klienta zachowana dla kompatybilności. Aktualne hosty ASP.NET Core muszą ustawić ją jawnie na mapowaną gałąź middleware.
`ResPath`	`""`	Ustaw jawnie na ścieżkę wbudowanych obrazów.
`cacheEnabled` / `cacheCount` / `cacheDelay`	`false` / `3` / `3`	Okno wczytywania stron w pamięci oraz opóźnienie.
`autoLoad`	`false`	Zalecany jest jawny przepływ tokenów.
`largeDoc`	`true`	Różni się od domyślnej wartości w C#.
`fixedZoom`	`false`	Różni się od domyślnej wartości w C#.
`fixedZoomPercent` / `fixedZoomPercentMobile`	`100` / `50`	Wartość mobilna różni się od C# (`75`).
`showHyperlinks`	`true`	Wymaga wyodrębnienia po stronie serwera, aby wygenerować nakładki.

Ustaw wszystkie istotne wartości 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: '/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 postępowało do strony.
`onThumbsShown`	none	Panel miniatur stał się widoczny.
`onAnnLoaded`	none	Dane adnotacji zostały załadowane.
`onAnnSaved`	none	Dane adnotacji zostały 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()`
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 również wewnętrzne pomocniki. Traktuj jako stabilne punkty integracji tylko metody używane przez interfejs referencyjny i udokumentowane tutaj lub w przewodnikach funkcji.

Ponawianie, gdy rozproszona strona jest nadal renderowana

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łączone, widget odpyta z tymi domyślnymi wartościami JavaScript:

Opcja	Domyślne
`retryInitialDelayMs`	`250`
`retryBackoffFactor`	`1.6`
`retryMaxDelayMs`	`2500`
`retryMaxAttempts`	`60`
`retryMaxTotalMs`	`120000`

Pozostaw wyłączone dla normalnego podglądu. Włączenie nie może uczynić nieobsługiwanego synchronicznego renderowania asynchronicznym.

Lista kontrolna ścieżek

DoconutOptions.MiddlewarePath musi opisywać gałąź, którą faktycznie mapujesz.
BasePath musi wskazywać tę gałąź.
DoconutOptions.ResourcesPath jest ścieżką wbudowanych zasobów.
ResPath zazwyczaj wskazuje podfolder /images.
ExtractHyperlinks musi być włączone w konfiguracji formatu serwera, zanim showHyperlinks będzie mógł coś wyświetlić.