ViewerConfig

Optionen für das Client-Viewer-Widget

ViewerConfig (Namespace Doconut) beschreibt das Aussehen und Verhalten des Browser‑Viewers. Es beeinflusst nicht die Dokumentdarstellungsqualität; dafür verwenden Sie eine Formatkonfiguration. Die C#‑Klasse und das langjährige JavaScript‑Widget haben unterschiedliche Vorgaben, daher Werte explizit zuordnen.

Zwei clientseitige Änderungen in dieser Version schlagen stillschweigend fehl. Handler‑Funktionen werden als Optionen übergeben — das Widget leitet seine Ereignis‑Callbacks nicht mehr aus der Container‑ID ab — und ResPath muss auf das Ressourcen‑Präfix statt auf das Anwendungs‑Root zeigen. Beide lassen den Server einwandfrei arbeiten und melden nichts in der Browser‑Konsole. Wenn Sie eine Seite aus der vorherigen Bibliothek übernehmen, lesen Sie Rückrufe und Pfad‑Checkliste, bevor Sie etwas anderes tun.

C#-Eigenschaften

TypEigenschaftStandardBeschreibung
boolShowThumbstrueZeigt das Miniatur‑Panel an.
boolAutoLoadfalseLädt automatisch nach der Initialisierung. Der normale Token‑Ablauf ruft View(token) explizit auf.
boolAutoFocustrueVerschiebt den Browser‑Fokus/Scrollen während der Initialisierung zum Viewer.
boolAutoPageFocustrueHält die aktuelle Miniatur sichtbar, während sich die Seiten ändern.
intPageZoom100Anfänglicher Zoom‑Prozentsatz.
intZoomStep10Prozentsatz, der durch Zoom‑Befehle hinzugefügt oder entfernt wird.
intMaxZoom300Maximaler Zoom‑Prozentsatz.
boolShowToolTiptrueZeigt den Seiten‑Positions‑Tooltip beim Scrollen an.
stringToolTipPageText"Page "Präfix, das im Seiten‑Tooltip verwendet wird.
boolCacheEnabledfalseBehält ein rollierendes Fenster von Seitenbildern im Browser‑Speicher. Es verwendet nicht localStorage.
boolLargeDocfalseFügt Seitenelemente in zeitgesteuerten Stapeln für große Dokumente hinzu.
boolShowHyperlinksfalseRendern von Hyperlink‑Overlays, wenn die Server‑Konfiguration sie extrahiert hat.
boolFixedZoomtrueVerwendet einen festen Zoom‑Prozentsatz anstelle einer responsiven Neuberechnung.
intFixedZoomPercent100Fester Desktop‑Zoom.
intFixedZoomPercentMobile75Fester mobiler Zoom.
stringBasePath"/"Wo der Viewer Seitenanfragen sendet. "/" ist DocImage.axd an der Seitenwurzel; andernfalls der Zweig, in dem der Host UseDoconut() zuordnet, ohne ein führendes / ("doconut" bedeutet /doconut/DocImage.axd).
stringResPath"doconut-res/images" (26.9.0; "doconut-res" before)Ordner, aus dem das Widget seine eigenen Bilder lädt: der images‑Ordner unter ResourcesPath, ohne ein führendes /.
stringFitType"width""width", "height" oder leer für kein automatisches Anpassen. "page" wird vom aktuellen Widget nicht akzeptiert.
boolRetryOn409falseAktiviert das Polling, wenn asynchrone/verteilte Seitenerstellung 202 Accepted antwortet; 409 wird ebenfalls für die Kompatibilität mit älteren Servern akzeptiert. Nicht nötig für den normalen synchronen Viewer.
csharp
var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "doconut",           // kein führender '/' : der Viewer fügt ihn hinzu ("/doconut" würde zu //doconut, ein anderer Host)
    ResPath = "doconut-res/images",
    ShowHyperlinks = true
};

C#-zu-JavaScript-Abbildung

Übergeben Sie kein direkt serialisiertes ViewerConfig an docViewer(...). Die meisten Widget‑Schlüssel sind camelCase, während drei etablierte Pfad‑/Fit‑Schlüssel PascalCase sind.

C#JavaScript
ShowThumbsshowThumbs
AutoLoadautoLoad
AutoFocusautoFocus
AutoPageFocusautoPageFocus
PageZoompageZoom
ZoomStepzoomStep
MaxZoommaxZoom
ShowToolTipshowToolTip
ToolTipPageTexttoolTipPageText
CacheEnabledcacheEnabled
LargeDoclargeDoc
ShowHyperlinksshowHyperlinks
FixedZoomfixedZoom
FixedZoomPercentfixedZoomPercent
FixedZoomPercentMobilefixedZoomPercentMobile
BasePathBasePath
ResPathResPath
FitTypeFitType
RetryOn409retryOn409

JavaScript-Standardwerte

Das Widget hat ältere Standardwerte, die von der C#‑Klasse abweichen. Die folgenden Werte stammen aus der aktuellen docViewer.js‑Implementierung.

OptionStandardHinweise
leftMinWidth / leftMaxWidth220 / 800Grenzwerte für die Breite des Miniaturbildbereichs.
showThumbstrueAnfängliche Sichtbarkeit der Miniaturbilder.
autoFocus / autoPageFocustrue / falseautoPageFocus weicht vom C#‑Standard ab.
thumbWidth / thumbHeight / thumbPadding150 / 200 / 10Miniaturbildgeometrie in Pixeln.
pageZoom / zoomStep / maxZoom100 / 10 / 200JavaScript maxZoom weicht von C# (300) ab.
showToolTip / toolTipPageTexttrue / "Page "Tooltip zur Seitenposition.
format / doc / AccessToken"" / 0 / ""Interne Initialisierungswerte; normalerweise von View(token) bereitgestellt.
debugModefalseZusätzliche Client‑Diagnosen.
FitType""Keine automatische Anpassung, sofern nicht angegeben.
BasePath"DocImage.axd"Historischer Client‑Standard aus Kompatibilitätsgründen beibehalten. Aktuelle ASP.NET Core‑Hosts müssen ihn explizit auf den zugeordneten Middleware‑Zweig setzen.
ResPath""Explizit auf den Pfad der eingebetteten Bilder setzen.
cacheEnabled / cacheCount / cacheDelayfalse / 3 / 3Im Speicher vorgeladene Seitenfenster und Verzögerung.
autoLoadfalseExpliziter Token‑Fluss wird empfohlen.
largeDoctrueWeicht vom C#‑Standard ab.
fixedZoomfalseWeicht vom C#‑Standard ab.
fixedZoomPercent / fixedZoomPercentMobile100 / 50Mobiler Wert weicht von C# (75) ab.
showHyperlinkstrueErfordert serverseitige Extraktion, um Overlays zu erzeugen.

Setzen Sie alle verhaltensrelevanten Werte, anstatt sich auf einen der Standardwerte zu verlassen:

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>

Rückrufe

RückrufArgumenteZweck
onPageLoadingpageNumEine Seitenanforderung wird gestartet.
onPageLoadedpageNumEin Seitenbild wurde geladen.
onThumbnailClickedpageNumDer Benutzer hat eine Miniatur ausgewählt.
onPageClickedpageNumDer Benutzer hat eine Seite ausgewählt.
onDoubleClicknoneDer Viewer hat einen Doppelklick erhalten.
onViewerBusynoneDer Viewer ist in einen beschäftigten Zustand gewechselt.
onViewerReadynoneInitialisierung abgeschlossen.
onViewerErrornoneDer Viewer ist in den Fehlermodus gewechselt.
onErrormessageEin Vorgang hat eine Fehlermeldung zurückgegeben.
onCopydataTextkopierdaten sind verfügbar.
onAutoLoadStatuspageNumDas automatische Laden hat eine Seite erreicht.
onThumbsShownnoneDas Miniaturbild‑Panel wurde sichtbar.
onAnnLoadednoneAnmerkungsdaten wurden geladen.
onAnnSavednoneAnmerkungsdaten wurden gespeichert.
onAnnSaveErrornoneSpeichern der Anmerkungen fehlgeschlagen.
onAnnClosednoneAnmerkungs‑UI geschlossen.

Halten Sie Rückrufe schnell; senden Sie Telemetrie asynchron und blockieren Sie das Rendern der Seite nicht.

Jeder dieser Punkte ist eine Option im Init‑Objekt. Der vorherige Viewer suchte globale Funktionen, deren Namen er aus der Container‑ID ableitete – eine Seite mit <div id="div_ctlDoc"> musste nur function ctlDoc_OnViewerReady() deklarieren. Diese Suche ist weg. Übergeben Sie die Funktion explizit:

javascript
function ctlDoc_OnViewerBusy() { /* zeige deinen Busy-Indikator */ }
function ctlDoc_OnViewerReady() { /* verstecke ihn */ }
function ctlDoc_Copy(text) { /* verwende den kopierten Text */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* Fortschritt melden */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... deine bestehenden Optionen ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // wurde nach Namen gefunden
    onViewerReady:    ctlDoc_OnViewerReady,     // wurde nach Namen gefunden
    onCopy:           ctlDoc_Copy,              // war ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // war ctlDoc_AutoLoadStatus(page)
});

Die alte Suche war in ein leeres catch eingebettet, sodass nie etwas gemeldet wurde. In dieser Version werden die Funktionen einfach nie ausgeführt: Das typische Symptom ist ein ständig drehender Busy‑Spinner, der nie aufhört, weil der Handler, der ihn ausblendet, onViewerReady war. Das dahinterliegende Dokument wird korrekt gerendert.

Zwei Anmerkungs‑Speicher‑Hooks werden weiterhin nach Namen gesucht: SaveAnnotations() ruft <elementId>_BeforeAnnSave() und <elementId>_DeletedAnnotationIds() auf, wenn sie existieren, und verwendet dabei die vollständige ID des Elements (div_ctlDoc_BeforeAnnSave für das obige Beispiel).

Es gibt keinen Link‑Klick‑Rückruf — die Hyperlink‑Verarbeitung ist integriert und wird von showHyperlinks gesteuert.

Öffentliche Methoden-Gruppen

GruppeGemeinsame Methoden
LebenszyklusView(token, accessToken?), Close(server?), Token(), Init(), IsLoaded()
NavigationGotoPage(page), ShowPage(page, focus?), Next(next), CurrentPage(), TotalPages()
Zoom und AnpassenZoom(zoomIn), CurrentZoom(), FitType(value), Refit()
AusrichtungRotate(page, angle), Flip(page, flipType)
VorschaubilderHideThumbs(hide), ThumbSize(size), ReloadThumbs(width), ScrollToThumb(thumb)
SucheCanSearch(), Search(...), SearchMatchCount(), SearchSummary(...), GotoSearchMatch(...)
AnnotationSaveAnnotations(), GetAnnotations(), PushAnnotations(...), CloseAnnotations(...), ShowAnnotations(...)
KopierenCopy(...), CopyPage(pageNumber), CopyMode(enabled)

Die JavaScript‑Datei enthält ebenfalls interne Hilfsfunktionen. Behandeln Sie nur Methoden, die von der Referenz‑UI verwendet und hier oder in den Feature‑Leitfäden dokumentiert sind, als stabile Integrationspunkte.

Erneut versuchen, während eine verteilte Seite noch gerendert wird

retryOn409 behält seinen historischen Namen bei. Es dient der asynchronen Seitenerstellung und versucht die aktuelle 202 Accepted Bereitschaftsantwort sowie das ältere 409 Conflict Signal erneut. Wenn aktiviert, fragt das Widget mit diesen JavaScript-Standardwerten ab:

OptionStandard
retryInitialDelayMs250
retryBackoffFactor1.6
retryMaxDelayMs2500
retryMaxAttempts150
retryMaxTotalMs300000

Lassen Sie es für den normalen Single-Node-Viewer deaktiviert. Das Aktivieren kann ein nicht unterstütztes synchrones Rendering nicht asynchron machen.

Aktivieren Sie es, wenn Seiten aus gemeinsam genutztem Speicher mit FirstPagePriority bereitgestellt werden, wobei spätere Seiten legitimerweise 202 Accepted beantworten, bis sie geschrieben sind. Ein Client, der nicht erneut versucht, zeigt fehlerhafte Kacheln für noch rendernde Seiten – siehe Verteilte Deployments.

Pfad-Checkliste

  • DoconutOptions.MiddlewarePath muss den Zweig beschreiben, den Sie tatsächlich zuordnen.
  • BasePath muss diesen Zweig anvisieren, geschrieben ohne ein führendes / ('doconut', nicht '/doconut': Der Viewer fügt den Schrägstrich hinzu, und //doconut/... ist eine Anfrage an einen anderen Host). Eine gängige Konfiguration behält die historische DocImage.axd Anfragestruktur auf einem MapWhen Zweig bei und setzt daher BasePath: '/'.
  • DoconutOptions.ResourcesPath ist die eingebettete Ressourcenroute.
  • ResPath zielt normalerweise auf sein images Unterverzeichnis ab, ohne ein führendes / — 'doconut-res/images' mit dem Standardpräfix. Ein leeres ResPath war in der vorherigen Bibliothek korrekt, wo Ressourcen vom Anwendungsstamm kamen; hier ist es nicht korrekt und es schlägt fehl, ohne einen Fehler anzuzeigen.
  • ExtractHyperlinks muss in der Serverformat-Konfiguration aktiviert sein, bevor showHyperlinks irgendetwas anzeigen kann.

War diese Seite hilfreich?