Annotations
Ajouter la prise en charge des annotations au visualiseur
Les annotations dans Doconut fonctionnent dans deux sens : les utilisateurs les dessinent dans le widget du navigateur et le serveur les persiste page par page, ou votre code les crée de manière programmatique et les charge dans une session ouverte. Dans les deux cas, elles sont rendues sur les pages et peuvent être intégrées aux exportations PDF/PNG.
La prise en charge des annotations est conditionnée par la capacité de licence Annotation (accordée automatiquement avec une licence Temporaire active).
Activer l'interface d'annotation
L'annotation est un module du Viewer, pas une barre d'outils autonome. La page complète doit inclure les ressources du Viewer, la barre d'outils du Viewer, le montage du Viewer, et le objViewer initialisé ; le ruban d'annotation est ensuite monté et attaché à cette même instance.
Émettez les bundles d'annotation en même temps que les bundles du viewer — ils sont conditionnés par la licence, ainsi les balises n'apparaissent que lorsque la capacité est disponible :
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeViewerCss = true,
IncludeAnnotationCss = true // jquery-ui.min.css + annotationBar.css
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeViewerScripts = true,
IncludeAnnotationScripts = true, // jquery-ui, raphael.js, annotation.js
IncludeAnnotationBar = true // le ruban d'annotation intégré
}))Conservez la composition complète du Viewer visible dans le balisage :
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Contrôles du visualiseur, y compris le bouton qui ouvre Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>Le bundle d'annotation génère le DOM du ruban à l'intérieur de annBarMount ; vous n'avez pas besoin de copier ses boutons ou le balisage du dialogue. Initialisez d'abord docViewer, puis créez le ruban uniquement lorsque le serveur confirme que l'annotation est sous licence :
<script>
let annBar = null;
let currentToken = '';
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: 'doconut',
ResPath: 'doconut-res/images',
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: (message) => console.error('Viewer error:', message)
});
@if (Viewer.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token: currentToken }),
onStatus: (message) => console.log(message),
onToast: (message, type) => console.log(type, message),
onLayout: () => requestAnimationFrame(() => objViewer.Refit())
});
annBar.attach(objViewer);
</text>
}
</script>Sans la capacité, ReferenceScripts omet le script du ruban, de sorte que le if côté serveur empêche qu'un appel non protégé à doconutAnnotationBar(...) ne casse la page.
L'enregistrement depuis le ruban envoie les données via le middleware (AnnSave), qui les stocke dans la session du document page par page. Le chargement (AnnLoad) se produit automatiquement lorsqu'une page contenant des annotations est rendue. Les quatre rappels onAnn* maintiennent le ruban synchronisé avec le cycle de vie du viewer.
Ouvrez‑le et fermez‑le depuis n'importe quelle barre d'outils du Viewer appartenant à l'hôte :
annBar.open();
annBar.close();L'API publique du ruban est :
| Méthode | Objectif |
|---|---|
attach(objViewer) | Connecter le ruban au viewer initialisé ; requis une fois |
open() / close() | Entrer ou quitter le mode d'édition d'annotation |
reset() | Retourner le ruban à son état fermé, non‑édition |
isOpen() / annotating() | Lire l'état du ruban / l'état d'édition d'annotation du viewer |
reopenEditable() | Recharger les annotations de la page courante en tant qu'objets éditables |
updateActionState() | Rafraîchir la disponibilité des contrôles d'enregistrement/suppression après les changements de l'hôte |
headerSlot() | Obtenir le slot d'extension d'en-tête optionnel pour les contrôles appartenant à l'hôte |
onStatus, onToast, onLayout, onEditStart et onEditEnd sont des rappels d'hôte optionnels. L'objet endpoints peut en outre fournir exportPdf, exportPng, imageUpload et imageList ; les contrôles sans point de terminaison configuré restent cachés.
Pour la séquence de démarrage combinée du Viewer, de la Recherche et des Annotations, voir Démarrage rapide.
Le bundle d'annotation ajoute les outils d'édition du navigateur, mais les données appartiennent toujours à la session du document côté serveur identifiée par le jeton. Réouvrir la source crée une nouvelle session ; conservez le XML ou l'enveloppe d'annotation encodée dans votre application si les annotations doivent survivre au-delà de la durée de vie de la session.
Deux types de rappel, câblés de deux manières
Le code d'annotation utilise deux styles de rappel, et chaque échoue silencieusement lorsqu'il est câblé dans l'autre sens :
onAnnLoaded,onAnnSaved,onAnnSaveError,onAnnClosedsont options dedocViewer({...}), comme chaque rappel du visualiseur.Created,Changed,Deleted, etPropertiessont des fonctions globales trouvées par leur nom : l'ID du visualiseur préfixé à l'événement. Pour le visualiseur dans#div_ctlDoc, l'ID estctlDoc, donc les fonctions sontctlDoc_Created,ctlDoc_Changed,ctlDoc_Deleted, etctlDoc_Properties. Une fonction mal orthographiée ou renommée n'est simplement jamais appelée.
SaveAnnotations() ne renvoie pas si l'enregistrement a réussi : le résultat arrive via onAnnSaved ou onAnnSaveError. Le code qui lit sa valeur de retour ne supprime jamais son drapeau « modifications non enregistrées ».
Créer des annotations en C#
Obtenez un gestionnaire lié à la session ouverte, ajoutez des annotations et chargez‑les (avec using Doconut.Annotations; pour les types et using System.Drawing; pour Rectangle/Color) :
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
// Lié aux dimensions de page de la session ouverte
var manager = viewer.GetAnnotationManager(token);
var pageCount = viewer.GetPageCount(token);
// Un tampon par page
for (int page = 1; page <= pageCount; page++)
{
manager.Add(new StampAnnotation(page, new Rectangle(30, 20, 240, 90),
$"PAGE {page}", 28, 4, Color.Maroon)
{
Opacity = 60,
Rotate = -8
});
}
manager.Add(new NoteAnnotation(1, new Rectangle(420, 150, 220, 120),
"Loaded from C# code.", Color.FromArgb(255, 255, 255, 170), 14));
// Charger dans la session — le widget les récupère via AnnLoad et le
// renderer les intègre dans les exportations image/PDF.
viewer.LoadAnnotationData(token, manager);
return Results.Ok();
});Types d'annotation
Tous les types résident dans Doconut.Annotations et héritent de BaseAnnotation (numéro de page + Rectangle de délimitation) :
| Type | Notes |
|---|---|
StampAnnotation | Tampon texte avec taille de police, bordure, couleur ; prend en charge Opacity, Rotate |
NoteAnnotation | Note autocollante avec texte, couleur de fond, taille de police, TitleColor |
RectangleAnnotation | Couleurs de bordure + remplissage, Title/ShowTitle |
CircleAnnotation | Bordure + remplissage, ShowBorder |
EllipseAnnotation | Bordure + remplissage, ShowBorder |
TriangleAnnotation | Couleur de bordure, BackColor, ShowBorder |
LineAnnotation | Ligne droite avec épaisseur et couleur |
ArrowAnnotation | Ligne avec pointe de flèche ; Direction réglable (type ArrowDirection, points cardinaux, défaut E) |
FreehandAnnotation | Trait libre à partir de points FreehandData encodés |
ImageAnnotation | Image depuis une URL. Une URL relative est résolue par rapport à l'hôte de la requête lorsque l'annotation est ajoutée ; le serveur récupère l'image uniquement au moment de la gravure — voir la note d'exportation ci‑dessous |
L'API AnnotationManager
| Membre | Objectif |
|---|---|
Add(BaseAnnotation) | Mettre en file d'attente une annotation |
GetAnnotations() / GetAnnotations(int page) | Inspecter ce que le gestionnaire détient |
ClearAnnotations() / ClearAnnotations(int page) | Supprimer tout / par page |
GetAnnotationData() / GetAnnotationData(int page) | Chaîne de données d'annotation encodée — une enveloppe Base64 (ce que le widget consomme) |
GetAnnotationXml() | Forme XML |
Viewer reflète les opérations de chargement/lecture par rapport à une session : LoadAnnotationData(token, manager) ou LoadAnnotationData(token, encodedData) (l'enveloppe Base64 provenant de GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).
Exporter avec les annotations intégrées
// PDF de toutes les pages avec les annotations rendues dessus
app.MapGet("/api/annotations/export-pdf", async (string token, Viewer viewer) =>
{
byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100);
return Results.File(pdf, "application/pdf", "export.pdf");
});
// Ou un ZIP de PNGs par page
app.MapGet("/api/annotations/export-png-zip", async (string token, Viewer viewer) =>
{
byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100);
return Results.File(zip, "application/zip", "annotations-png.zip");
});Les exportations utilisent le même brûleur que le rendu à l'écran, ainsi ce que les utilisateurs voient est ce que le fichier contient — sauf pour les annotations d'image, décrites ci‑après.
Annotations d'image sur un hôte intranet exportées comme « Image bloquée »
Le visualiseur et l'export récupèrent l'image d'un(e) ImageAnnotation depuis des emplacements différents :
| Surface | Qui télécharge l'image | Sur un hôte intranet ou de développement |
|---|---|---|
| Le visualiseur dans le navigateur | Le navigateur de l'utilisateur | L'image apparaît |
ExportAnnotationsToPdfAsync / …PngZipAsync | Le serveur | Un espace réservé rouge « Image bloquée » |
Lorsque le serveur récupère une image pour l'intégrer, il refuse les adresses qui renvoient vers des réseaux privés : boucle locale (localhost, 127.0.0.1), 0.0.0.0, lien-local (169.254.x.x), les plages privées 10.x, 172.16–31.x et 192.168.x, NAT de niveau opérateur (100.64.0.0/10), ainsi que les adresses IPv6 lien-local et unique-local. Cela protège le serveur contre une utilisation visant à atteindre des systèmes internes via une URL d'image manipulée, et il n'existe aucun commutateur pour le désactiver.
Une URL d'image relative se résout par rapport à l'hôte de la requête en cours, ainsi, sur localhost, sur un serveur intranet, ou sur tout site atteint via une adresse privée, l'image s'affiche dans le visualiseur et l'export contient à la place l'espace réservé. C'est la protection qui fonctionne, pas un échec de rendu. Si les exports doivent contenir l'image, servez‑la depuis un hôte avec une adresse publique et utilisez une URL absolue. Un nom d'hôte qui ne peut pas être résolu est refusé de la même manière ; toute autre erreur de téléchargement affiche l'URL et le message d'erreur en rouge à l'endroit où l'image aurait dû être.
Flux de travail de persistance
- Ouvrez le document et obtenez son jeton.
- Chargez le XML ou les données encodées précédemment stockées dans ce jeton.
- Laissez le widget lire et modifier les annotations de la session.
- Récupérez le XML avec
GetAnnotationXML(token)lorsque votre application décide de le persister. - Exportez en PDF/PNG lorsqu'un livrable aplati est requis.
- Fermez la session du document.
N'utilisez pas le jeton opaque du visualiseur comme identifiant permanent d'annotation. Associez les données d'annotation persistées à vos propres identifiants de document et de version.
Notes de sécurité et de rendu
- Les requêtes d'annotation utilisent la même sécurité de session/jeton que les requêtes de page.
- Validez et contrôlez toute URL d'image fournie par l'utilisateur afin d'éviter les falsifications de requêtes côté serveur.
- Les exports appliquent la même décision de licence / filigrane personnalisé que le rendu de page à l'écran.
- Les gros contenus libres et les exports haute résolution augmentent l'utilisation de mémoire ; testez des documents réalistes et des valeurs de zoom.
Dépannage
| Symptôme | Vérification |
|---|---|
| Le ruban d'annotation est absent | capacité Annotation et les quatre indicateurs CSS/script d'annotation |
| Le rappel de sauvegarde signale une erreur | expiration du jeton/de la session et middleware BasePath |
ctlDoc_Created (ou une autre fonction d'événement) ne s'exécute jamais | Le nom de la fonction : id du visualiseur + _ + événement, en tant que fonction globale |
| Les annotations C# n'apparaissent pas | La numérotation des pages commence à 1 et les données ont été chargées dans le jeton actif |
| L'annotation d'image apparaît à l'écran mais pas dans l'export | L'hôte de l'image possède une adresse privée ou de boucle locale — voir ci‑dessus |
| Le document rouvert n'a aucune annotation | Persistez le XML/les données en dehors de la session du visualiseur, puis chargez‑les dans le nouveau jeton |
Cette page était-elle utile ?