Introduction

Le poste d’introduction couvre brièvement les annotations: surlignages, soulignements, notes autocollantes et tampons, ajoutés via Page.AddHighlight(), Page.AddUnderline() et des méthodes similaires. Ce n’est qu’une petite partie de ce que Page prend réellement en charge — la galerie d’annotations de cette bibliothèque comprend le balisage, les formes libres, les liens avec une navigation réelle et des actions de soumission de formulaire, ainsi que la recherche, le tout accessible directement depuis Page.

Cet article parcourt le reste de cette surface: les méthodes d’annotation de forme et à main levée, ce que l’action d’une annotation Link peut réellement faire, et les deux manières différentes de rechercher le contenu d’une annotation selon que le texte recherché se trouve dans l’apparence de l’annotation ou dans son commentaire /Contents.

Chaque méthode d’annotation renvoie un handle typé limité à l’annotation qu’elle vient de créer, et chaque annotation sur une page est lisible par la suite via page.Annotations.

Ce qui est inclus

Annotations de balisage

Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() et Page.AddStrikeOut() acceptent tous la même forme d’options— un ensemble de points quadrilatéraux délimitant la région de texte et une couleur optionnelle— et les quatre renvoient un MarkupAnnotation. Les points quadrilatéraux sont généralement dérivés d’une recherche de texte ou d’un rectangle de texte connu.

const markup = (body: [number, number, number, number], sample: string,
  add: (quads: number[]) => void): void => {
  const yMid = (body[1] + body[3]) / 2 - 6;
  const textRect: [number, number, number, number] = [body[0] + 4, yMid, body[2] - 4, yMid + 16];
  page.AddText(sample, textRect[0], textRect[1], { fontSize: 12 });
  add(rectToQuads(textRect));
};

markup(cardBody, 'Highlight this phrase', (quads) =>
  page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' }));
markup(cardBody, 'Underline this phrase', (quads) =>
  page.AddUnderline({ quads, color: [0, 0, 1] }));
markup(cardBody, 'Squiggle this phrase', (quads) =>
  page.AddSquiggly({ quads, color: [1, 0.5, 0] }));
markup(cardBody, 'Strike this phrase out', (quads) =>
  page.AddStrikeOut({ quads, color: [1, 0, 0] }));

Notes et texte autonome

Page.AddTextNote() ajoute une icône de note autocollante classique qui ouvre une fenêtre contextuelle de commentaire lorsqu’on clique, renvoyant un TextAnnotation. Page.AddFreeText() dessine plutôt son texte directement sur la page à l’intérieur d’une boîte bordurée, avec sa propre taille de police, alignement et couleur de remplissage — utile pour les encadrés qui doivent être visibles sans rien ouvrir.

page.AddTextNote({
  rect: [x, y, x + 20, y + 20], icon: 'Note', author: 'Reviewer',
  contents: 'This is a sticky-note annotation.',
});

page.AddFreeText({
  rect: [220, 60, 520, 96],
  contents: 'FreeText sample', fontSize: 10, align: 'center',
  fill: [1, 1, 0.8], width: 1,
});

Formes et encre à main levée

Page.AddSquare() et Page.AddCircle() dessinent un rectangle ou une ellipse bordés, chacun avec un remplissage intérieur facultatif. Page.AddLine() trace une ligne droite entre deux points, avec des styles de tête de flèche sélectionnables indépendamment (startEnding/endEnding, par ex. 'OpenArrow'/'ClosedArrow') à chaque extrémité. Page.AddPolygon() et Page.AddPolyline() dessinent des formes à plusieurs points, fermées ou ouvertes, à partir d’une liste plate de coordonnées, et Page.AddInk() enregistre un ou plusieurs traits de stylo à main levée comme paths de listes de points.

page.AddSquare({ rect: [50, 400, 130, 435], color: [0.8, 0, 0], fill: [1, 1, 0.5], width: 2 });
page.AddCircle({ rect: [150, 400, 230, 435], color: [0, 0.5, 0], width: 2 });

page.AddLine({
  line: [260, 417, 420, 417],
  color: [0, 0, 0.7], width: 2,
  startEnding: 'OpenArrow', endEnding: 'ClosedArrow',
});

const stroke: number[] = [];
[-8, 6, -4, 10, -2, 8, -6].forEach((dy, i) => stroke.push(440 + i * 12, 417 + dy));
page.AddInk({ paths: [stroke], color: [0.6, 0, 0.6], width: 2 });

Liens et leurs actions

Page.AddLink() renvoie un LinkAnnotation dont le action décide de ce qui se passe au clic: { type: 'uri', uri: '...' } ouvre une URL externe, { type: 'goto', page: N } saute à une page du même document, et { type: 'submit', url: '...', format: 'html' } soumet les valeurs actuelles des champs de formulaire à un point de terminaison. Un numéro de page goto hors plage ou un objet d’action mal formé est rejeté lors de la création plutôt que d’être accepté silencieusement.

const uriLink = page.AddLink({
  rect: [10, 10, 100, 30], action: { type: 'uri', uri: 'https://example.com' },
});

const gotoLink = page.AddLink({
  rect: [10, 40, 100, 60], action: { type: 'goto', page: 2 },
});

const submitLink = page.AddLink({
  rect: [10, 70, 100, 90],
  action: { type: 'submit', url: 'https://example.com/post', format: 'html' },
});

// page.AddLink({ rect: [...], action: { type: 'goto', page: 99 } }) throws RangeError
// when 99 is out of range for the document.

Recherche du contenu des annotations

Deux méthodes différentes recherchent le texte des annotations, et elles sont délibérément distinctes : Page.SearchAnnotations() recherche le texte de l’apparence propre d’une annotation dessine — l’étiquette visible sur un FreeText ou un tampon, par exemple — tandis que Page.SearchAnnotationText() recherche le texte porté dans l’annotation /Contents entrée, comme le corps du commentaire d’une note autocollante. Une correspondance dans l’un n’implique pas de correspondance dans l’autre.

page.SearchAnnotations('bravo');          // finds it if the annotation's drawn appearance contains it
page.SearchAnnotationText('bravo');       // finds it if the annotation's /Contents comment contains it

Les annotations dont vous n’avez plus besoin peuvent être supprimées directement avec Page.RemoveAnnotation(), en passant soit le handle de l’annotation, soit son dictionnaire sous-jacent.

Démarrage rapide

Installez le package, puis ajoutez un surlignage, un lien et une note autocollante à une page existante :

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build
import { Document } from '@asposefoss/pdf';

const doc = Document.OpenFile('input.pdf');
const page = doc.Pages[0];

page.AddHighlight({ quads: [72, 700, 300, 700, 72, 715, 300, 715], color: [1, 1, 0] });

page.AddLink({
  rect: [72, 670, 200, 690], action: { type: 'uri', uri: 'https://example.com' },
});

page.AddTextNote({
  rect: [320, 670, 340, 690], icon: 'Note', author: 'Reviewer',
  contents: 'Please double-check this figure.',
});

doc.WriteTo('annotated.pdf');

Formats pris en charge

FormatExtensionLireÉcrire
PDFpdf✓✓
Markdownmd✓✓
SVGsvg✓✓
TIFFtiff✓✓
DOCXdocx—✓
HTMLhtml—✓
PNGpng—✓
EPUBepub—✓

Open source & licences

Aspose.PDF FOSS pour TypeScript est publié sous la licence MIT, le code source étant disponible sur GitHub. Il n’y a aucun filigrane d’évaluation, aucune limite d’utilisation, ni de fichier de licence séparé à gérer, et la bibliothèque peut être utilisée dans des produits commerciaux sans redevances.

Le package est actuellement en version 0.1.0, reflétant un développement actif en phase précoce. Node.js (>=22) est la seule exigence d’exécution, et le package n’a aucune autre dépendance tierce.

Premiers pas

Ressources associées