Annotations PDF

Annotations PDF

Page.annotations expose un AnnotationCollection — une vue mutable, semblable à une séquence, sur chaque annotation d’une page. Chaque entrée est un Annotation (ou les sous-classes MarkupAnnotation / LinkAnnotation), et les données spécifiques au sous-type telles que les points quad, les listes d’encre ou les couleurs sont lues et écrites via get_property() / set_property() plutôt que par des attributs dédiés.

Ajout d’annotations

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) crée une nouvelle annotation et l’ajoute à la page. subtype accepte soit une chaîne brute ("Text", "Square", "Highlight") ou un membre d’énumération AnnotationType.

import aspose_pdf
from aspose_pdf import Document, AnnotationType

doc = Document()
doc.pages.add()
page = doc.pages[0]

# Plain string subtype
page.annotations.add("Text", (100, 100, 200, 200), "Hello")

# AnnotationType enum, with subtype-specific properties
page.annotations.add(
    AnnotationType.POLYGON,
    (0, 0, 10, 10),
    "",
    properties={"Vertices": [0, 0, 10, 0, 5, 10]},
)

Lecture et mise à jour des propriétés

get_property(name, default) lit une valeur spécifique au sous-type; set_property(name, value) en écrit une, et définir une propriété à None la retire du dictionnaire properties de l’annotation.

doc = Document()
doc.pages.add()
page = doc.pages[0]

ann = page.annotations.add(
    "Square", (0, 0, 50, 50), "x", properties={"C": [1, 0, 0]},
)
ann.set_property("IC", [0, 0, 1])
print(page.annotations[0].get_property("IC"))  # [0, 0, 1]

ann.set_property("C", None)  # removes the "C" entry entirely
print("C" in page.annotations[0].properties)  # False

Nommer les annotations avec AnnotationName

Les noms PDF (p.ex. l’entrée Name d’une annotation Stamp) sont marqués de façon distincte des chaînes simples à l’aide de AnnotationName, une sous-classe str de aspose_pdf.engine.cos. Une valeur stockée de cette manière reste égale à une chaîne ordinaire.

from aspose_pdf.engine.cos import AnnotationName

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add(
    "Stamp", (10, 10, 110, 60), "",
    properties={"Name": AnnotationName("Approved")},
)

Insertion, suppression et vidage

insert(index, subtype, rect, contents, title, appearance_normal, properties) place une nouvelle annotation à une position spécifique; delete(index) en supprime une par indice (lève IndexError pour un indice hors limites); clear() supprime toutes les annotations de la page.

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add("Text", (0, 0, 100, 100), "A")
page.annotations.add("Text", (200, 200, 300, 300), "C")
page.annotations.insert(1, "Text", (100, 100, 200, 200), "B")
# order is now: A, B, C

page.annotations.delete(1)   # removes "B"
page.annotations.clear()     # removes everything remaining

Génération des apparences d’annotation

Annotation.generate_appearance(force) construit le flux d’apparence /AP /N pour une annotation et renvoie True lorsqu’un moteur de rendu pour ce sous-type existe; AnnotationCollection.generate_appearances(force) fait de même pour chaque annotation de la page en un seul appel et renvoie le nombre d’annotations réellement générées (les sous-types non pris en charge sont ignorés).

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add("Square", (0, 0, 50, 50), "")
page.annotations.add("Circle", (60, 0, 110, 50), "")
page.annotations.add("Text", (0, 60, 20, 80), "")  # unsupported subtype -> skipped

generated = page.annotations.generate_appearances()
print(generated)  # 2

Sous-types d’annotation et drapeaux

AnnotationType énumère les noms de sous-type standard du PDF 32000-1:2008 (Tableau169): TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, POLY_LINE, HIGHLIGHT, UNDERLINE, SQUIGGLY, STRIKE_OUT, STAMP, CARET, INK, POPUP, FILE_ATTACHMENT, SOUND, MOVIE, WIDGET, SCREEN, PRINTER_MARK, TRAP_NET, WATERMARK et REDACT.

AnnotationFlags est un IntFlag couvrant le comportement d’affichage/interaction des annotations: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED et TOGGLE_NO_VIEW.

Version préliminaire: annotations 3D

PDF3DAnnotation, PDF3DArtwork, PDF3DContent et PDF3DView modélisent une œuvre d’art 3D attachée à une page — un PDF3DAnnotation possède un rect: Rectangle, un artwork: PDF3DArtwork et un background_color: Color optionnel. PDF3DArtwork.add_view() enregistre un PDF3DView, chacun portant un render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) et un lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM). La docstring de la bibliothèque elle-même marque PDF3DAnnotation comme un «minimal annotation wrapper for prerelease imports» — considérez cette surface comme en phase précoce plutôt que comme un API d’authoring 3D pleinement abouti.

Conseils et meilleures pratiques

• Privilégiez les membres d’énumération AnnotationType plutôt que les chaînes de sous-type brutes lorsque la valeur doit également être comparée ou utilisée dans une branche ailleurs dans votre code.
• Appelez set_property(name, None) pour supprimer une propriété directement plutôt que de laisser une valeur obsolète en place — l’entrée disparaît complètement de properties.
• Générez les apparences par lots avec AnnotationCollection.generate_appearances au lieu de boucler generate_appearance() par annotation; cela renvoie le nombre réel d’éléments générés afin que vous puissiez détecter les sous-types sautés ou non pris en charge.
• delete() et l’indexation dans page.annotations sont toutes deux à base zéro; validez un indice avant d’appeler delete() s’il provient d’une entrée utilisateur, car un indice hors limites déclenche IndexError.
• Encapsulez les valeurs de noms PDF (comme le Name d’un Stamp) dans AnnotationName afin qu’elles circulent comme des noms PDF plutôt que comme des chaînes de texte simples.

Problèmes courants

FAQ

Comment ajouter une annotation de commentaire en texte brut ?

Appelez page.annotations.add("Text", (x0, y0, x1, y1), "comment text"). Le tuple à quatre nombres représente le rectangle de l’annotation sur la page.

Quelle est la différence entre Annotation, MarkupAnnotation et LinkAnnotation?

Annotation est la vue en direct renvoyée pour toute annotation sur une page. MarkupAnnotation constitue la base des sous-types de type balisage (surbrillances, notes texte, formes) et LinkAnnotation est conservé pour les annotations de type lien; les deux exposent actuellement la même surface de méthodes/propriétés que Annotation.

Puis-je supprimer une propriété unique sans supprimer l’ensemble de l’annotation?

Oui — appelez annotation.set_property(name, None); l’annotation elle-même reste intacte, seule cette entrée est supprimée de properties.

Est-ce que AnnotationCollection.generate_appearances échoue si un sous-type n’est pas pris en charge?

Non. Il ignore les sous-types sans moteur d’apparence intégré et renvoie le nombre d’annotations pour lesquelles il a réellement généré une apparence.

Les classes d’annotation 3D sont-elles prêtes pour la production?

PDF3DAnnotation et les types associés sont documentés comme un wrapper minimal pour les importations pré-release — vérifiez le comportement avec votre visionneuse PDF cible avant de les utiliser pour du contenu 3D en production.

Résumé API Reference

Voir aussi

• Aspose.PDF for Python — Enterprise Documentation