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
ResPathmuss 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
| Typ | Eigenschaft | Standard | Beschreibung |
|---|---|---|---|
bool | ShowThumbs | true | Zeigt das Miniatur‑Panel an. |
bool | AutoLoad | false | Lädt automatisch nach der Initialisierung. Der normale Token‑Ablauf ruft View(token) explizit auf. |
bool | AutoFocus | true | Verschiebt den Browser‑Fokus/Scrollen während der Initialisierung zum Viewer. |
bool | AutoPageFocus | true | Hält die aktuelle Miniatur sichtbar, während sich die Seiten ändern. |
int | PageZoom | 100 | Anfänglicher Zoom‑Prozentsatz. |
int | ZoomStep | 10 | Prozentsatz, der durch Zoom‑Befehle hinzugefügt oder entfernt wird. |
int | MaxZoom | 300 | Maximaler Zoom‑Prozentsatz. |
bool | ShowToolTip | true | Zeigt den Seiten‑Positions‑Tooltip beim Scrollen an. |
string | ToolTipPageText | "Page " | Präfix, das im Seiten‑Tooltip verwendet wird. |
bool | CacheEnabled | false | Behält ein rollierendes Fenster von Seitenbildern im Browser‑Speicher. Es verwendet nicht localStorage. |
bool | LargeDoc | false | Fügt Seitenelemente in zeitgesteuerten Stapeln für große Dokumente hinzu. |
bool | ShowHyperlinks | false | Rendern von Hyperlink‑Overlays, wenn die Server‑Konfiguration sie extrahiert hat. |
bool | FixedZoom | true | Verwendet einen festen Zoom‑Prozentsatz anstelle einer responsiven Neuberechnung. |
int | FixedZoomPercent | 100 | Fester Desktop‑Zoom. |
int | FixedZoomPercentMobile | 75 | Fester mobiler Zoom. |
string | BasePath | "/" | 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). |
string | ResPath | "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 /. |
string | FitType | "width" | "width", "height" oder leer für kein automatisches Anpassen. "page" wird vom aktuellen Widget nicht akzeptiert. |
bool | RetryOn409 | false | Aktiviert 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. |
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 |
|---|---|
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 |
JavaScript-Standardwerte
Das Widget hat ältere Standardwerte, die von der C#‑Klasse abweichen. Die folgenden Werte stammen aus der aktuellen docViewer.js‑Implementierung.
| Option | Standard | Hinweise |
|---|---|---|
leftMinWidth / leftMaxWidth | 220 / 800 | Grenzwerte für die Breite des Miniaturbildbereichs. |
showThumbs | true | Anfängliche Sichtbarkeit der Miniaturbilder. |
autoFocus / autoPageFocus | true / false | autoPageFocus weicht vom C#‑Standard ab. |
thumbWidth / thumbHeight / thumbPadding | 150 / 200 / 10 | Miniaturbildgeometrie in Pixeln. |
pageZoom / zoomStep / maxZoom | 100 / 10 / 200 | JavaScript maxZoom weicht von C# (300) ab. |
showToolTip / toolTipPageText | true / "Page " | Tooltip zur Seitenposition. |
format / doc / AccessToken | "" / 0 / "" | Interne Initialisierungswerte; normalerweise von View(token) bereitgestellt. |
debugMode | false | Zusä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 / cacheDelay | false / 3 / 3 | Im Speicher vorgeladene Seitenfenster und Verzögerung. |
autoLoad | false | Expliziter Token‑Fluss wird empfohlen. |
largeDoc | true | Weicht vom C#‑Standard ab. |
fixedZoom | false | Weicht vom C#‑Standard ab. |
fixedZoomPercent / fixedZoomPercentMobile | 100 / 50 | Mobiler Wert weicht von C# (75) ab. |
showHyperlinks | true | Erfordert serverseitige Extraktion, um Overlays zu erzeugen. |
Setzen Sie alle verhaltensrelevanten Werte, anstatt sich auf einen der Standardwerte zu verlassen:
<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ückruf | Argumente | Zweck |
|---|---|---|
onPageLoading | pageNum | Eine Seitenanforderung wird gestartet. |
onPageLoaded | pageNum | Ein Seitenbild wurde geladen. |
onThumbnailClicked | pageNum | Der Benutzer hat eine Miniatur ausgewählt. |
onPageClicked | pageNum | Der Benutzer hat eine Seite ausgewählt. |
onDoubleClick | none | Der Viewer hat einen Doppelklick erhalten. |
onViewerBusy | none | Der Viewer ist in einen beschäftigten Zustand gewechselt. |
onViewerReady | none | Initialisierung abgeschlossen. |
onViewerError | none | Der Viewer ist in den Fehlermodus gewechselt. |
onError | message | Ein Vorgang hat eine Fehlermeldung zurückgegeben. |
onCopy | data | Textkopierdaten sind verfügbar. |
onAutoLoadStatus | pageNum | Das automatische Laden hat eine Seite erreicht. |
onThumbsShown | none | Das Miniaturbild‑Panel wurde sichtbar. |
onAnnLoaded | none | Anmerkungsdaten wurden geladen. |
onAnnSaved | none | Anmerkungsdaten wurden gespeichert. |
onAnnSaveError | none | Speichern der Anmerkungen fehlgeschlagen. |
onAnnClosed | none | Anmerkungs‑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:
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
| Gruppe | Gemeinsame Methoden |
|---|---|
| Lebenszyklus | View(token, accessToken?), Close(server?), Token(), Init(), IsLoaded() |
| Navigation | GotoPage(page), ShowPage(page, focus?), Next(next), CurrentPage(), TotalPages() |
| Zoom und Anpassen | Zoom(zoomIn), CurrentZoom(), FitType(value), Refit() |
| Ausrichtung | Rotate(page, angle), Flip(page, flipType) |
| Vorschaubilder | HideThumbs(hide), ThumbSize(size), ReloadThumbs(width), ScrollToThumb(thumb) |
| Suche | CanSearch(), Search(...), SearchMatchCount(), SearchSummary(...), GotoSearchMatch(...) |
| Annotation | SaveAnnotations(), GetAnnotations(), PushAnnotations(...), CloseAnnotations(...), ShowAnnotations(...) |
| Kopieren | Copy(...), 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:
| Option | Standard |
|---|---|
retryInitialDelayMs | 250 |
retryBackoffFactor | 1.6 |
retryMaxDelayMs | 2500 |
retryMaxAttempts | 150 |
retryMaxTotalMs | 300000 |
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.MiddlewarePathmuss den Zweig beschreiben, den Sie tatsächlich zuordnen.BasePathmuss 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 historischeDocImage.axdAnfragestruktur auf einemMapWhenZweig bei und setzt daherBasePath: '/'.DoconutOptions.ResourcesPathist die eingebettete Ressourcenroute.ResPathzielt normalerweise auf seinimagesUnterverzeichnis ab, ohne ein führendes/—'doconut-res/images'mit dem Standardpräfix. Ein leeresResPathwar in der vorherigen Bibliothek korrekt, wo Ressourcen vom Anwendungsstamm kamen; hier ist es nicht korrekt und es schlägt fehl, ohne einen Fehler anzuzeigen.ExtractHyperlinksmuss in der Serverformat-Konfiguration aktiviert sein, bevorshowHyperlinksirgendetwas anzeigen kann.
War diese Seite hilfreich?