Comment travailler avec les annotations PDF en C++

Aspose.PDF FOSS for C++ représente chaque annotation PDF comme une sous-classe de la classe de base commune Annotation, et expose les annotations sur une page via le AnnotationCollection renvoyé par Page::Annotations(). Ce guide ajoute une annotation de note texte simple et une annotation stylisée à une page avec TextAnnotation, enregistre le document, puis le rouvre pour lire les annotations et en supprimer une. La bibliothèque est intégrée dans un projet CMake en tant que dépendance de sous-répertoire — il n’y a aucune étape d’installation via un registre de paquets.

Guide étape par étape

add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

#include <aspose/pdf/document.hpp>
#include <iostream>

int main() {
    Aspose::Pdf::Document doc;
    std::cout << "Linked OK — pages: " << doc.Pages().Count() << "\n";
}

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/page_collection.hpp>
#include <aspose/pdf/rectangle.hpp>
#include <aspose/pdf/color.hpp>
#include <aspose/pdf/annotations/annotation.hpp>
#include <aspose/pdf/annotations/annotation_collection.hpp>
#include <aspose/pdf/annotations/annotation_type.hpp>
#include <aspose/pdf/annotations/annotation_flags.hpp>
#include <aspose/pdf/annotations/border.hpp>
#include <aspose/pdf/annotations/border_style.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc;
Page page = doc.Pages().Add();

TextAnnotation note{doc};
note.Rect(Rectangle(100.0, 700.0, 200.0, 720.0, false));
note.Contents("Reviewed and approved.");

page.Annotations().Add(note);

TextAnnotation flagged{doc};
flagged.Rect(Rectangle(100.0, 600.0, 300.0, 650.0, false));
flagged.Contents("Needs follow-up");
flagged.Color(Color::FromRgb(220, 20, 20));
flagged.Flags(AnnotationFlags::Print | AnnotationFlags::ReadOnly);
flagged.Border().Width(2);
flagged.Border().Style(BorderStyle::Dashed);

page.Annotations().Add(flagged);

doc.Save("annotated.pdf");

Document reopened("annotated.pdf");
auto& annots = reopened.Pages()[1].Annotations();

std::cout << "Annotation count: " << annots.Count() << "\n";

for (int i = 0; i < annots.Count(); ++i) {
    const auto& a = annots[i];
    if (a.AnnotationType() == AnnotationType::Text) {
        std::cout << "Text annotation: " << a.Contents() << "\n";
    }
}

annots.Delete(0);
reopened.Save("annotated-cleaned.pdf");

Problèmes courants et solutions

Rien ne change dans le PDF enregistré après l’appel Annotations().Add()

Deux choses posent souvent problème ici. Premièrement, PageCollection est basé à 1 (doc.Pages()[1] est la première page) tandis que AnnotationCollection est basé à 0 (annots[0] est la première annotation) — confondre les deux schémas d’indexation conduit à agir sur le mauvais objet. Deuxièmement, assurez-vous que Document::Save() s’exécute réellement après l’ajout de l’annotation ; rien n’est écrit sur le disque avant cela.

AnnotationCollection indexation ou Delete(index) throws std::out_of_range

Les indices valides vont de 0 à Count() - 1. Fournir un indice négatif ou un indice égal ou supérieur à Count() lance std::out_of_range par conception. Appelez Count() d’abord pour délimiter toute boucle ou recherche.

Remove() returns false la deuxième fois que je l’appelle sur la même annotation

Ce n’est pas une erreur. Remove() indique si l’annotation a été trouvée et supprimée en tant que bool; l’appeler à nouveau sur une annotation déjà disparue ne fait rien et renvoie false. Vérifiez la valeur de retour au lieu de supposer que Remove() réussit toujours.

Définir une nouvelle AnnotationFlags valeur efface les flags que j’avais déjà définis

Flags(value) remplace l’ensemble complet de drapeaux — il ne fusionne pas avec la valeur précédente. Pour ajouter ou supprimer un drapeau unique, lisez d’abord les drapeaux actuels et combinez-les avec des opérateurs binaires, par exemple a.Flags(a.Flags() | AnnotationFlags::Print) pour ajouter un drapeau, ou a.Flags(a.Flags() & ~AnnotationFlags::Print) pour en supprimer un tout en laissant les autres intacts.

Foire aux questions

Quelle est la relation entre Annotation, TextAnnotation et les autres sous-types d’annotation?

Annotation est la classe de base commune. TextAnnotation et les autres types d’annotation concrets la spécialisent chacun pour un sous-type d’annotation PDF, tout en partageant les accesseurs Rect(), Contents(), Color(), Flags() et Border() de la classe de base.

Les annotations sont-elles limitées à l’ensemble du document ou à une seule page?

Chaque page possède son propre AnnotationCollection, renvoyé par la méthode Annotations() de cette page. Les annotations sont toujours limitées à la page à laquelle elles ont été ajoutées, et non au document dans son ensemble.

Comment puis-je compter le nombre d’annotations présentes sur une page?

Appelez Count() sur le AnnotationCollection renvoyé par Page::Annotations().

Une annotation peut-elle être à la fois imprimable et en lecture seule simultanément?

Oui. AnnotationFlags est un champ de bits, il faut donc combiner les valeurs avec un OU binaire, par exemple AnnotationFlags::Print | AnnotationFlags::ReadOnly.

La suppression d’une annotation de AnnotationCollection la supprime-t-elle du fichier PDF sur le disque?

Uniquement après l’exécution de Document::Save(). Delete(), Remove() et Clear() ne modifient que la collection en mémoire — le PDF sur le disque reste inchangé jusqu’à ce que le document soit enregistré.

Voir aussi

• Travailler avec les annotations PDF (Guide du développeur)
• Guide d’installation
• API Reference
• Aspose.PDF FOSS for C++ — Page produit
• Dépôt GitHub
• Aspose.PDF for C++ — Enterprise Knowledge Base