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’appel Add*() — une annotation obtenue en relisant page.Annotations par la suite est une référence d’objet différente.
  • SearchAnnotationText() et SearchAnnotations() 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 option encrypt restent valides après la réouverture et le déchiffrement du document.

Problèmes courants

ProblèmeCauseCorrection
page.Annotations.find() renvoie undefined pour une annotation que vous venez d’ajouterRecherche d’un tableau obsolète capturé avant que l’annotation ne soit ajoutéeRelisez 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 pageLe texte est dessiné par l’annotation (par ex. le corps d’un FreeText), et non transporté dans /ContentsUtilisez 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éeAppelez 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éthodeDescription
AnnotationPoigné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
TextAnnotationUne poignée /Text de note autocollante ; ajoute Icon, Open, Author
StampAnnotationUne poignée /Stamp de tampon en caoutchouc ; ajoute StampName
MarkupAnnotationUn 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.AnnotationsChaque 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

Voir aussi

 Français