Annotations
Vue d’ensemble
Cette page couvre la création, la lecture, la recherche et l’aplatissement des annotations PDF. Page expose une méthode Add*() par sous-type d’annotation, chacune renvoyant un handle Annotation actif; la classe de base Annotation et ses sous-types (TextAnnotation, StampAnnotation, MarkupAnnotation et d’autres) exposent les propriétés de l’annotation pour la lecture et la modification.
Création d’annotations de balisage, de note et de lien
Les quatre méthodes de balisage de texte — Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() et Page.AddStrikeOut() — prennent un tableau quads (/QuadPoints) et renvoient un MarkupAnnotation. Page.AddLink() crée une zone cliquable avec une URI ou une action interne, et Page.AddTextNote() ajoute une icône de note autocollante qui ouvre une popup avec du texte contents, renvoyant un TextAnnotation.
page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' });
page.AddUnderline({ quads, color: [0, 0, 1] });
page.AddStrikeOut({ quads, color: [1, 0, 0] });
page.AddLink({
rect: [100, 700, 220, 716],
action: { type: 'uri', uri: 'https://example.com' },
border: 0,
});
page.AddTextNote({
rect: [x, y, x + 20, y + 20], icon: 'Note', author: 'Reviewer',
contents: 'This is a sticky-note annotation.',
});Page expose également des méthodes de forme et de dessin libre — AddSquare(), AddCircle(), AddLine(), AddPolygon(), AddPolyline(), AddInk(), AddFreeText(), AddCaret() et AddStamp() — chacune renvoyant le handle d’annotation correspondant à ce sous-type, générant automatiquement son apparence /AP.
Lecture et listage des annotations
page.Annotations est un tableau de chaque Annotation sur la page. Chaque annotation, quel que soit son sous-type, expose Subtype, Rect, Color, Contents, Name, Layer, ModDate, Flags, Print, Hidden et Opacity; les sous-types ajoutent leurs propres champs, tels que StampAnnotation.StampName ou MarkupAnnotation.QuadPoints.
const freeText = page.Annotations.find((a) => a.Subtype === 'FreeText');
if (freeText) {
freeText.Contents = 'Updated note text';
}Recherche du texte d’annotation
Page.SearchAnnotationText() and Page.SearchAnnotations() sont délibérément disjointes. SearchAnnotationText() trouve des correspondances dans le texte d’une annotation carries plutôt que dessine — celle d’une note /Contents, son auteur (/T), ou son sujet (/Subj) — et retourne AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() trouve des correspondances dans le texte d’une annotation draws, tel qu’un FreeTextles mots visibles de ’s, et renvoie AnnotationMatch[] ({ annot, text, quads }).
// A sticky note's /Contents text — found by SearchAnnotationText, not SearchAnnotations.
const textHits = page.SearchAnnotationText('body secret');
console.log(textHits[0].key, textHits[0].value); // 'Contents' 'body secret'
// A FreeText's rendered words — found by SearchAnnotations, not SearchAnnotationText.
const drawnHits = page.SearchAnnotations('bravo');Aplatissement des annotations
Annotation.Flatten() intègre l’apparence /AP d’une annotation directement dans le flux de contenu de la page à son /Rect, puis la supprime de /Annots. Le résultat est un contenu permanent et statique — il n’est plus une annotation distincte que le lecteur peut cliquer, modifier ou masquer.
const note = page.AddTextNote({
rect: [72, 660, 92, 680], icon: 'Comment', contents: 'Reviewed and approved.',
});
note.Flatten();Conseils et bonnes pratiques
- Appelez
Flatten()sur l’objet renvoyé directement par l’appelAdd*()— une annotation obtenue en relisantpage.Annotationspar la suite est une référence d’objet différente. SearchAnnotationText()etSearchAnnotations()couvrent des textes différents: exécutez les deux si vous devez trouver une phrase, qu’elle ait été tapée dans une note ou dessinée sur la page.- Les quatre méthodes de balisage (
AddHighlight,AddUnderline,AddSquiggly,AddStrikeOut) génèrent automatiquement leur apparence/AP— aucun dessin manuel du flux de contenu n’est requis. - Le chiffrement survit à un aller-retour: les annotations ajoutées avant
Document.Save()avec une optionencryptrestent valides après la réouverture et le déchiffrement du document.
Problèmes courants
| Problème | Cause | Correction |
|---|---|---|
page.Annotations.find() renvoie undefined pour une annotation que vous venez d’ajouter | Recherche d’un tableau obsolète capturé avant que l’annotation ne soit ajoutée | Relisez page.Annotations après l’appel Add*(), ou utilisez directement le handle renvoyé par l’appel |
SearchAnnotationText() ne trouve rien pour le texte visible sur la page | Le texte est dessiné par l’annotation (par ex. le corps d’un FreeText), et non transporté dans /Contents | Utilisez SearchAnnotations() à la place — il correspond au texte dessiné |
L’annotation apparaît toujours comme modifiable après Flatten() | Flatten() a été appelé sur une copie plutôt que sur la poignée que Add*() a renvoyée | Appelez Flatten() sur l’objet renvoyé directement par la méthode de création |
FAQ
Quelle est la différence entre SearchAnnotationText et SearchAnnotations?
SearchAnnotationText() correspondances texte une annotation carries — /Contents, /T (author), ou /Subj — comme le corps d’une note autocollante. SearchAnnotations() correspondances texte une annotation draws sur la page, comme un FreeText’s mots visibles. Les deux sont disjoints : une correspondance dans l’un n’apparaîtra pas dans l’autre.
Comment rendre une annotation permanente et non interactive?
Appelez Flatten() sur la poignée Annotation renvoyée par la méthode Add*() qui l’a créée. Cela intègre son apparence dans le flux de contenu de la page et la supprime de /Annots.
Quels sous-types d’annotation sont pris en charge?
Page expose les méthodes de création pour le balisage de texte (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut), les notes et callouts (AddTextNote, AddFreeText, AddCaret), les liens (AddLink), les formes (AddSquare, AddCircle, AddLine, AddPolygon, AddPolyline), l’encre à main levée (AddInk), les tampons (AddStamp), et les pièces jointes de fichiers (AddFileAttachment).
Comment lister toutes les annotations déjà présentes sur une page?
Lisez page.Annotations, un tableau de poignées Annotation. Chaque expose Subtype, Rect, Color, Contents, ainsi que les autres propriétés communes, afin que vous puissiez les filtrer ou les inspecter avec les méthodes de tableau standard.
API Reference Résumé
| Classe/Méthode | Description |
|---|---|
Annotation | Poignée de base sur toute annotation ; expose Subtype, Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity |
Annotation.Flatten() | Intégrer l’apparence de l’annotation dans le contenu de page statique |
TextAnnotation | Une poignée /Text de note autocollante ; ajoute Icon, Open, Author |
StampAnnotation | Une poignée /Stamp de tampon en caoutchouc ; ajoute StampName |
MarkupAnnotation | Un gestionnaire de balisage de texte (Highlight/Underline/StrikeOut/Squiggly); ajoute MarkupType, QuadPoints |
Page.AddHighlight() / Page.AddUnderline() / Page.AddStrikeOut() / Page.AddSquiggly() | Créer une annotation de balisage de texte sur /QuadPoints |
Page.AddTextNote() | Créer une annotation de note autocollante |
Page.AddLink() | Créer un lien cliquable avec une URI ou une action interne |
Page.Annotations | Chaque Annotation sur la page, sous forme de tableau |
Page.SearchAnnotationText() | Trouver le texte qu’une annotation porte (/Contents, /T, /Subj) |
Page.SearchAnnotations() | Trouver le texte qu’une annotation dessine sur la page |