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
@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 :

html
<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 :

html
<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 :

javascript
annBar.open();
annBar.close();

L'API publique du ruban est :

MéthodeObjectif
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, onAnnClosed sont options de docViewer({...}), comme chaque rappel du visualiseur.
  • Created, Changed, Deleted, et Properties sont 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 est ctlDoc, donc les fonctions sont ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted, et ctlDoc_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) :

csharp
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) :

TypeNotes
StampAnnotationTampon texte avec taille de police, bordure, couleur ; prend en charge Opacity, Rotate
NoteAnnotationNote autocollante avec texte, couleur de fond, taille de police, TitleColor
RectangleAnnotationCouleurs de bordure + remplissage, Title/ShowTitle
CircleAnnotationBordure + remplissage, ShowBorder
EllipseAnnotationBordure + remplissage, ShowBorder
TriangleAnnotationCouleur de bordure, BackColor, ShowBorder
LineAnnotationLigne droite avec épaisseur et couleur
ArrowAnnotationLigne avec pointe de flèche ; Direction réglable (type ArrowDirection, points cardinaux, défaut E)
FreehandAnnotationTrait libre à partir de points FreehandData encodés
ImageAnnotationImage 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

MembreObjectif
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

csharp
// 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 :

SurfaceQui télécharge l'imageSur un hôte intranet ou de développement
Le visualiseur dans le navigateurLe navigateur de l'utilisateurL'image apparaît
ExportAnnotationsToPdfAsync / …PngZipAsyncLe serveurUn 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

  1. Ouvrez le document et obtenez son jeton.
  2. Chargez le XML ou les données encodées précédemment stockées dans ce jeton.
  3. Laissez le widget lire et modifier les annotations de la session.
  4. Récupérez le XML avec GetAnnotationXML(token) lorsque votre application décide de le persister.
  5. Exportez en PDF/PNG lorsqu'un livrable aplati est requis.
  6. 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ômeVérification
Le ruban d'annotation est absentcapacité Annotation et les quatre indicateurs CSS/script d'annotation
Le rappel de sauvegarde signale une erreurexpiration du jeton/de la session et middleware BasePath
ctlDoc_Created (ou une autre fonction d'événement) ne s'exécute jamaisLe nom de la fonction : id du visualiseur + _ + événement, en tant que fonction globale
Les annotations C# n'apparaissent pasLa 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'exportL'hôte de l'image possède une adresse privée ou de boucle locale — voir ci‑dessus
Le document rouvert n'a aucune annotationPersistez le XML/les données en dehors de la session du visualiseur, puis chargez‑les dans le nouveau jeton

Cette page était-elle utile ?