ViewerConfig

Options du widget de visualisation client

ViewerConfig (namespace Doconut) décrit l'apparence et le comportement du visualiseur du navigateur. Cela n'affecte pas la qualité du rendu du document ; utilisez une configuration de format pour cela. La classe C# et le widget JavaScript de longue date ont des valeurs par défaut différentes, il faut donc mapper les valeurs explicitement.

Deux changements côté client dans cette version échouent silencieusement. Les fonctions de gestionnaire sont passées en tant qu'options — le widget ne dérive plus ses rappels d'événement de l'identifiant du conteneur — et ResPath doit pointer vers le préfixe des ressources plutôt que vers la racine de l'application. Les deux laissent le serveur fonctionner parfaitement et n'affichent rien dans la console du navigateur. Si vous migrez une page depuis la bibliothèque précédente, lisez Callbacks et Path checklist avant toute chose.

Propriétés C#

TypePropriétéValeur par défautDescription
boolShowThumbstrueAfficher le panneau des miniatures.
boolAutoLoadfalseCharger automatiquement après l'initialisation. Le flux normal de jetons appelle explicitement View(token).
boolAutoFocustrueDéplacer le focus/scroll du navigateur vers le visualiseur pendant l'initialisation.
boolAutoPageFocustrueConserver la miniature actuelle visible pendant le changement de pages.
intPageZoom100Pourcentage de zoom initial.
intZoomStep10Pourcentage ajouté ou retiré par les commandes de zoom.
intMaxZoom300Pourcentage de zoom maximal.
boolShowToolTiptrueAfficher l'infobulle de position de page pendant le défilement.
stringToolTipPageText"Page "Préfixe utilisé dans l'infobulle de page.
boolCacheEnabledfalseConserver une fenêtre mobile d'images de page en mémoire du navigateur. Il n'utilise pas localStorage.
boolLargeDocfalseAjouter les éléments de page par lots chronométrés pour les documents volumineux.
boolShowHyperlinksfalseRendre les superpositions de liens hypertexte lorsque la configuration du serveur les a extraites.
boolFixedZoomtrueUtiliser un pourcentage de zoom fixe plutôt qu'un recalcul réactif.
intFixedZoomPercent100Zoom fixe sur ordinateur de bureau.
intFixedZoomPercentMobile75Zoom fixe sur mobile.
stringBasePath"/"Où le visualiseur envoie les requêtes de page. "/" est DocImage.axd à la racine du site ; sinon la branche où l'hôte mappe UseDoconut(), sans un / initial ("doconut" signifie /doconut/DocImage.axd).
stringResPath"doconut-res/images" (26.9.0 ; "doconut-res" avant)Dossier depuis lequel le widget charge ses propres images : le dossier images sous ResourcesPath, sans un / initial.
stringFitType"width""width", "height", ou vide pour aucun ajustement automatique. "page" n'est pas accepté par le widget actuel.
boolRetryOn409falseActiver le sondage lorsque la production de pages asynchrone/distribuée répond 202 Accepted ; 409 est également accepté pour la compatibilité avec les serveurs plus anciens. Non nécessaire pour le visualiseur synchrone normal.
csharp
var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "doconut",           // pas de '/' initial : le visualiseur l'ajoute ("/doconut" deviendrait //doconut, un autre hôte)
    ResPath = "doconut-res/images",
    ShowHyperlinks = true
};

Correspondance C# vers JavaScript

Ne transmettez pas un ViewerConfig directement sérialisé à docViewer(...). La plupart des clés du widget sont en camelCase, tandis que trois clés de chemin/ajustement établies sont en PascalCase.

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

Valeurs par défaut JavaScript

Le widget possède des valeurs par défaut plus anciennes qui diffèrent de la classe C#. Les valeurs suivantes proviennent de l'implémentation actuelle docViewer.js.

OptionValeur par défautRemarques
leftMinWidth / leftMaxWidth220 / 800Limites de largeur du volet des miniatures.
showThumbstrueVisibilité initiale des miniatures.
autoFocus / autoPageFocustrue / falseautoPageFocus diffère de la valeur par défaut C#.
thumbWidth / thumbHeight / thumbPadding150 / 200 / 10Géométrie des miniatures en pixels.
pageZoom / zoomStep / maxZoom100 / 10 / 200JavaScript maxZoom diffère de C# (300).
showToolTip / toolTipPageTexttrue / "Page "Info-bulle de position de page.
format / doc / AccessToken"" / 0 / ""Valeurs d'initialisation internes ; généralement renseignées par View(token).
debugModefalseDiagnostics client supplémentaires.
FitType""Aucun ajustement automatique sauf si fourni.
BasePath"DocImage.axd"Valeur par défaut historique du client conservée pour compatibilité. Les hôtes ASP.NET Core actuels doivent la définir explicitement sur la branche du middleware mappée.
ResPath""Définir explicitement sur le chemin des images intégrées.
cacheEnabled / cacheCount / cacheDelayfalse / 3 / 3Fenêtre et délai de préchargement de pages en mémoire.
autoLoadfalseLe flux de jetons explicite est recommandé.
largeDoctrueDiffère de la valeur par défaut C#.
fixedZoomfalseDiffère de la valeur par défaut C#.
fixedZoomPercent / fixedZoomPercentMobile100 / 50La valeur mobile diffère de C# (75).
showHyperlinkstrueNécessite une extraction côté serveur pour produire des superpositions.

Définissez toutes les valeurs importantes du comportement au lieu de vous fier à l'un ou l'autre des ensembles de valeurs par défaut :

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>

Rappels

RappelArgumentsObjectif
onPageLoadingpageNumUne requête de page démarre.
onPageLoadedpageNumLe chargement d'une image de page est terminé.
onThumbnailClickedpageNumL'utilisateur a sélectionné une miniature.
onPageClickedpageNumL'utilisateur a sélectionné une page.
onDoubleClicknoneLe visualiseur a reçu un double-clic.
onViewerBusynoneLe visualiseur est entré dans un état occupé.
onViewerReadynoneInitialisation terminée.
onViewerErrornoneLe visualiseur est entré dans son état d'erreur.
onErrormessageUne opération a renvoyé un message d'erreur.
onCopydataDes données de copie de texte sont disponibles.
onAutoLoadStatuspageNumLe chargement automatique a progressé vers une page.
onThumbsShownnoneLe panneau des miniatures est devenu visible.
onAnnLoadednoneDonnées d'annotation chargées.
onAnnSavednoneDonnées d'annotation enregistrées.
onAnnSaveErrornoneL'enregistrement de l'annotation a échoué.
onAnnClosednoneInterface d'annotation fermée.

Gardez les rappels rapides ; envoyez la télémétrie de façon asynchrone et ne bloquez pas le rendu de la page.

Chacune de ces options se trouve dans l'objet d'initialisation. Le visualiseur précédent recherchait les fonctions globales dont les noms étaient dérivés de l'ID du conteneur — une page avec <div id="div_ctlDoc"> n'avait qu'à déclarer function ctlDoc_OnViewerReady(). Cette recherche a disparu. Passez la fonction explicitement :

javascript
function ctlDoc_OnViewerBusy() { /* affichez votre indicateur d'activité */ }
function ctlDoc_OnViewerReady() { /* masquez-le */ }
function ctlDoc_Copy(text) { /* utilisez le texte copié */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* signaler la progression */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... vos options existantes ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // a été trouvé par nom
    onViewerReady:    ctlDoc_OnViewerReady,     // a été trouvé par nom
    onCopy:           ctlDoc_Copy,              // was ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // was ctlDoc_AutoLoadStatus(page)
});

L'ancienne recherche était encapsulée dans un catch vide, donc rien n'était jamais signalé. Dans cette version, les fonctions ne s'exécutent tout simplement jamais : le symptôme habituel est un indicateur d'activité qui ne s'arrête jamais, parce que le gestionnaire qui le masquait était onViewerReady. Le document derrière celui-ci se rend correctement.

Deux hooks d'enregistrement d'annotation sont encore recherchés par leur nom : SaveAnnotations() appelle <elementId>_BeforeAnnSave() et <elementId>_DeletedAnnotationIds() lorsqu'ils existent, en utilisant l'ID complet de l'élément (div_ctlDoc_BeforeAnnSave pour l'exemple ci‑dessus).

Il n'existe aucun rappel de clic sur un lien — la gestion des hyperliens est intégrée et pilotée par showHyperlinks.

Groupes de méthodes publiques

GroupeMéthodes communes
Cycle de vieView(token, accessToken?), Close(server?), Token(), Init(), IsLoaded()
NavigationGotoPage(page), ShowPage(page, focus?), Next(next), CurrentPage(), TotalPages()
Zoom et ajustementZoom(zoomIn), CurrentZoom(), FitType(value), Refit()
OrientationRotate(page, angle), Flip(page, flipType)
MiniaturesHideThumbs(hide), ThumbSize(size), ReloadThumbs(width), ScrollToThumb(thumb)
RechercheCanSearch(), Search(...), SearchMatchCount(), SearchSummary(...), GotoSearchMatch(...)
AnnotationSaveAnnotations(), GetAnnotations(), PushAnnotations(...), CloseAnnotations(...), ShowAnnotations(...)
CopieCopy(...), CopyPage(pageNumber), CopyMode(enabled)

Le fichier JavaScript contient également des aides internes. Ne considérez comme points d’intégration stables que les méthodes utilisées par l’interface de référence et documentées ici ou dans les guides fonctionnels.

Réessayer pendant qu’une page distribuée est encore en cours de rendu

retryOn409 conserve son nom historique. Il sert à la production de pages asynchrones et réessaye la réponse de disponibilité actuelle 202 Accepted ainsi que le signal plus ancien 409 Conflict. Lorsqu’il est activé, le widget interroge avec ces valeurs par défaut JavaScript :

OptionValeur par défaut
retryInitialDelayMs250
retryBackoffFactor1.6
retryMaxDelayMs2500
retryMaxAttempts150
retryMaxTotalMs300000

Laissez‑le désactivé pour le visualiseur mono‑nœud normal. L’activer ne peut pas rendre asynchrone un rendu synchrone non pris en charge.

Activez‑le lorsque les pages sont servies depuis un stockage partagé avec FirstPagePriority, où les pages ultérieures répondent légitimement 202 Accepted jusqu’à ce qu’elles soient écrites. Un client qui ne réessaye pas affiche des tuiles cassées pour les pages encore en cours de rendu — voir Déploiements distribués.

Checklist du chemin

  • DoconutOptions.MiddlewarePath doit décrire la branche que vous mappez réellement.
  • BasePath doit cibler cette branche, écrite sans le préfixe / ('doconut', pas '/doconut' : le visualiseur ajoute la barre oblique, et //doconut/... est une requête vers un autre hôte). Une configuration courante conserve la forme de requête historique DocImage.axd sur une branche MapWhen et définit donc BasePath: '/'.
  • DoconutOptions.ResourcesPath est la route des ressources intégrées.
  • ResPath cible normalement son sous‑dossier images, sans le préfixe / — 'doconut-res/images' avec le préfixe par défaut. Un ResPath vide était correct dans la bibliothèque précédente, où les ressources provenaient de la racine de l’application ; ce n’est pas correct ici, et cela échoue sans erreur.
  • ExtractHyperlinks doit être activé dans la configuration du format serveur avant que showHyperlinks puisse afficher quoi que ce soit.

Cette page était-elle utile ?