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
ResPathdoit 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#
| Type | Propriété | Valeur par défaut | Description |
|---|---|---|---|
bool | ShowThumbs | true | Afficher le panneau des miniatures. |
bool | AutoLoad | false | Charger automatiquement après l'initialisation. Le flux normal de jetons appelle explicitement View(token). |
bool | AutoFocus | true | Déplacer le focus/scroll du navigateur vers le visualiseur pendant l'initialisation. |
bool | AutoPageFocus | true | Conserver la miniature actuelle visible pendant le changement de pages. |
int | PageZoom | 100 | Pourcentage de zoom initial. |
int | ZoomStep | 10 | Pourcentage ajouté ou retiré par les commandes de zoom. |
int | MaxZoom | 300 | Pourcentage de zoom maximal. |
bool | ShowToolTip | true | Afficher l'infobulle de position de page pendant le défilement. |
string | ToolTipPageText | "Page " | Préfixe utilisé dans l'infobulle de page. |
bool | CacheEnabled | false | Conserver une fenêtre mobile d'images de page en mémoire du navigateur. Il n'utilise pas localStorage. |
bool | LargeDoc | false | Ajouter les éléments de page par lots chronométrés pour les documents volumineux. |
bool | ShowHyperlinks | false | Rendre les superpositions de liens hypertexte lorsque la configuration du serveur les a extraites. |
bool | FixedZoom | true | Utiliser un pourcentage de zoom fixe plutôt qu'un recalcul réactif. |
int | FixedZoomPercent | 100 | Zoom fixe sur ordinateur de bureau. |
int | FixedZoomPercentMobile | 75 | Zoom fixe sur mobile. |
string | BasePath | "/" | 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). |
string | ResPath | "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. |
string | FitType | "width" | "width", "height", ou vide pour aucun ajustement automatique. "page" n'est pas accepté par le widget actuel. |
bool | RetryOn409 | false | Activer 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. |
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 |
|---|---|
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 |
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.
| Option | Valeur par défaut | Remarques |
|---|---|---|
leftMinWidth / leftMaxWidth | 220 / 800 | Limites de largeur du volet des miniatures. |
showThumbs | true | Visibilité initiale des miniatures. |
autoFocus / autoPageFocus | true / false | autoPageFocus diffère de la valeur par défaut C#. |
thumbWidth / thumbHeight / thumbPadding | 150 / 200 / 10 | Géométrie des miniatures en pixels. |
pageZoom / zoomStep / maxZoom | 100 / 10 / 200 | JavaScript maxZoom diffère de C# (300). |
showToolTip / toolTipPageText | true / "Page " | Info-bulle de position de page. |
format / doc / AccessToken | "" / 0 / "" | Valeurs d'initialisation internes ; généralement renseignées par View(token). |
debugMode | false | Diagnostics 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 / cacheDelay | false / 3 / 3 | Fenêtre et délai de préchargement de pages en mémoire. |
autoLoad | false | Le flux de jetons explicite est recommandé. |
largeDoc | true | Diffère de la valeur par défaut C#. |
fixedZoom | false | Diffère de la valeur par défaut C#. |
fixedZoomPercent / fixedZoomPercentMobile | 100 / 50 | La valeur mobile diffère de C# (75). |
showHyperlinks | true | Né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 :
<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
| Rappel | Arguments | Objectif |
|---|---|---|
onPageLoading | pageNum | Une requête de page démarre. |
onPageLoaded | pageNum | Le chargement d'une image de page est terminé. |
onThumbnailClicked | pageNum | L'utilisateur a sélectionné une miniature. |
onPageClicked | pageNum | L'utilisateur a sélectionné une page. |
onDoubleClick | none | Le visualiseur a reçu un double-clic. |
onViewerBusy | none | Le visualiseur est entré dans un état occupé. |
onViewerReady | none | Initialisation terminée. |
onViewerError | none | Le visualiseur est entré dans son état d'erreur. |
onError | message | Une opération a renvoyé un message d'erreur. |
onCopy | data | Des données de copie de texte sont disponibles. |
onAutoLoadStatus | pageNum | Le chargement automatique a progressé vers une page. |
onThumbsShown | none | Le panneau des miniatures est devenu visible. |
onAnnLoaded | none | Données d'annotation chargées. |
onAnnSaved | none | Données d'annotation enregistrées. |
onAnnSaveError | none | L'enregistrement de l'annotation a échoué. |
onAnnClosed | none | Interface 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 :
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
| Groupe | Méthodes communes |
|---|---|
| Cycle de vie | View(token, accessToken?), Close(server?), Token(), Init(), IsLoaded() |
| Navigation | GotoPage(page), ShowPage(page, focus?), Next(next), CurrentPage(), TotalPages() |
| Zoom et ajustement | Zoom(zoomIn), CurrentZoom(), FitType(value), Refit() |
| Orientation | Rotate(page, angle), Flip(page, flipType) |
| Miniatures | HideThumbs(hide), ThumbSize(size), ReloadThumbs(width), ScrollToThumb(thumb) |
| Recherche | CanSearch(), Search(...), SearchMatchCount(), SearchSummary(...), GotoSearchMatch(...) |
| Annotation | SaveAnnotations(), GetAnnotations(), PushAnnotations(...), CloseAnnotations(...), ShowAnnotations(...) |
| Copie | Copy(...), 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 :
| Option | Valeur par défaut |
|---|---|
retryInitialDelayMs | 250 |
retryBackoffFactor | 1.6 |
retryMaxDelayMs | 2500 |
retryMaxAttempts | 150 |
retryMaxTotalMs | 300000 |
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.MiddlewarePathdoit décrire la branche que vous mappez réellement.BasePathdoit 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 historiqueDocImage.axdsur une brancheMapWhenet définit doncBasePath: '/'.DoconutOptions.ResourcesPathest la route des ressources intégrées.ResPathcible normalement son sous‑dossierimages, sans le préfixe/—'doconut-res/images'avec le préfixe par défaut. UnResPathvide é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.ExtractHyperlinksdoit être activé dans la configuration du format serveur avant queshowHyperlinkspuisse afficher quoi que ce soit.
Cette page était-elle utile ?