Lucrul cu adnotările PDF

Lucrul cu adnotări PDF

Adnotările PDF în Aspose.PDF FOSS pentru C++ sunt reprezentate de clasa de bază Annotation și subtipurile sale concrete (TextAnnotation, LinkAnnotation, HighlightAnnotation, FreeTextAnnotation, CircleAnnotation, WatermarkAnnotation, WidgetAnnotation și altele). Fiecare pagină expune adnotările prin Page.Annotations(), care returnează un AnnotationCollection. Acest ghid acoperă adăugarea de adnotări pe o pagină, iterarea și eliminarea acestora, citirea adnotărilor dintr-un document existent, atașarea acțiunilor de link, personalizarea aspectului și aplatizarea adnotărilor.

Adăugarea de adnotări pe o pagină

Creează o instanță concretă de adnotare, poziționeaz-o cu un Rectangle și adaug-o la colecția paginii cu AnnotationCollection.Add(). TextAnnotation reprezintă un comentariu de tip notiță lipicioasă ancorat la un punct pe pagină:

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>
#include <aspose/pdf/rectangle.hpp>

int main() {
    Aspose::Pdf::Document doc("input.pdf");
    auto& page = doc.Pages()[1];

    Aspose::Pdf::Annotations::TextAnnotation note(doc);
    note.Rect(Aspose::Pdf::Rectangle(100.0, 700.0, 200.0, 720.0, false));
    note.Contents("Reviewed and approved");

    page.Annotations().Add(note);
    doc.Save("annotated.pdf");
}

Annotation.Contents() / Contents(value) obțin și setează textul notiței, iar Annotation.Rect() / Rect(value) poziționează adnotarea pe pagină.

Iterarea și eliminarea adnotărilor

AnnotationCollection suportă numărarea, accesul indexat, verificările de apartenență și eliminarea prin valoare sau prin index:

#include <aspose/pdf/document.hpp>

int main() {
    Aspose::Pdf::Document doc("input.pdf");
    auto& annotations = doc.Pages()[1].Annotations();

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

    for (int i = 0; i < annotations.Count(); ++i) {
        std::cout << "Contents: " << annotations[i].Contents() << "\n";
    }

    if (annotations.Count() > 0) {
        annotations.Delete(0);   // remove by index
    }
    annotations.Clear();         // remove everything
}

AnnotationCollection.Contains(annotation) și Remove(annotation) operează pe o referință de adnotare specifică; Delete(index) elimină prin poziție, iar Delete(annotation) elimină o adnotare specifică fără a-i necesita indexul. IsReadOnly() raportează dacă colecția poate fi modificată.

Citirea adnotărilor dintr-un document existent

Când un document este încărcat, adnotările sale sunt deja populate și pot fi inspectate fără a adăuga nimic. Annotation.AnnotationType() raportează subtipul (AnnotationType::Text, AnnotationType::Highlight, AnnotationType::Link, AnnotationType::FreeText, AnnotationType::FileAttachment, AnnotationType::Watermark și altele):

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/annotation_type.hpp>

int main() {
    Aspose::Pdf::Document doc("annotated.pdf");
    auto& annotations = doc.Pages()[1].Annotations();

    for (int i = 0; i < annotations.Count(); ++i) {
        auto& a = annotations[i];
        if (a.AnnotationType() == Aspose::Pdf::Annotations::AnnotationType::Text) {
            std::cout << "Note: " << a.Contents() << "\n";
        }
    }
}

Ordinea adnotărilor și subtipul sunt păstrate pe parcursul unui ciclu de salvare/reîncărcare, astfel încât codul care indexează în Annotations() după încărcarea unui document vede aceeași secvență care era prezentă când fișierul a fost scris.

Adnotări de tip link și acțiuni

LinkAnnotation atașează o regiune clicabilă la o pagină și declanșează un PdfAction când este activat. NamedAction sare la o țintă de navigare predefinită, JavascriptAction execută un șir ECMAScript, iar SubmitFormAction trimite date de formular către un URL printr-un FileSpecification:

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/link_annotation.hpp>
#include <aspose/pdf/annotations/named_action.hpp>
#include <aspose/pdf/annotations/predefined_action.hpp>
#include <aspose/pdf/rectangle.hpp>

int main() {
    Aspose::Pdf::Document doc;
    auto page = doc.Pages().Add();

    Aspose::Pdf::Annotations::LinkAnnotation link(
        page, Aspose::Pdf::Rectangle(0.0, 0.0, 100.0, 20.0, false));
    link.Action(Aspose::Pdf::Annotations::NamedAction(
        Aspose::Pdf::Annotations::PredefinedAction::LastPage));

    page.Annotations().Add(link);
    doc.Save("linked.pdf");
}

LinkAnnotation.Action(value) acceptă orice subtip PdfAction și îl clonează intern, astfel încât adnotarea păstrează propria copie a acțiunii. LinkAnnotation.Destination() / Destination(value) setează o țintă de navigare explicită în loc de o acțiune, iar Highlighting() / Highlighting(value) controlează feedback-ul vizual afișat în timp ce linkul este apăsat.

Aspectul adnotării: bordură, flaguri și culoare

Fiecare Annotation expune un Border, un bitfield de AnnotationFlags, și un Color folosit pentru a reda aspectul său:

#include <aspose/pdf/annotations/border_style.hpp>
#include <aspose/pdf/annotations/annotation_flags.hpp>
#include <aspose/pdf/color.hpp>

// 'note' is an existing Annotation reference, e.g. from AnnotationCollection.
note.Border().Width(2);
note.Border().Style(Aspose::Pdf::Annotations::BorderStyle::Dashed);
note.Flags(Aspose::Pdf::Annotations::AnnotationFlags::Print);
note.Color(Aspose::Pdf::Color::Red());

Border.Style() acceptă BorderStyle::Solid, Dashed, Beveled, Inset sau Underline. Border.Effect() suportă, de asemenea, un contur BorderEffect::Cloudy cu EffectIntensity() care controlează cât de pronunțat este. AnnotationFlags este un bitfield — combinați valori precum Print, NoZoom, ReadOnly și LockedContents pentru a controla cum se comportă o adnotare într-un vizualizator fără a schimba conținutul său vizibil.

Aplatizarea adnotărilor

O singură adnotare poate fi aplatizată — fuzionată în conținutul paginii și făcută neinteractivă — prin apelarea directă a Annotation.Flatten():

#include <aspose/pdf/document.hpp>

int main() {
    Aspose::Pdf::Document doc("annotated.pdf");
    auto& annotations = doc.Pages()[1].Annotations();
    for (int i = 0; i < annotations.Count(); ++i) {
        annotations[i].Flatten();
    }
    doc.Save("flattened.pdf");
}

Pentru operațiuni de adnotare la nivel de document, PdfAnnotationEditor urmează modelul Facade partajat utilizat în API: legați un document sursă cu BindPdf(), aplicați una sau mai multe operațiuni de adnotare, apoi scrieți rezultatul cu Save():

#include <aspose/pdf/facades/pdf_annotation_editor.hpp>

int main() {
    Aspose::Pdf::Facades::PdfAnnotationEditor editor;
    editor.BindPdf("annotated.pdf");
    editor.FlatteningAnnotations();
    editor.Save("flattened.pdf");
}

PdfAnnotationEditor.DeleteAnnotations() elimină fiecare adnotare din documentul legat; DeleteAnnotations(annotType) restricționează eliminarea la o singură AnnotationType. ImportAnnotationsFromXfdf(xfdfFile) și ImportAnnotationsFromFdf(fdfFile) încarcă date de adnotare exportate dintr-un alt vizualizator PDF.

Sfaturi și bune practici

• Adăugați întotdeauna o adnotare nou construită la Page.Annotations() înainte de a apela Document.Save() — o adnotare care nu este niciodată adăugată la o colecție nu este scrisă în fișierul de ieșire.
• Utilizați AnnotationCollection.Contains(annotation) înainte de a apela Remove() dacă nu sunteți sigur că adnotarea este încă prezentă; Remove() returnează false în loc să arunce o excepție când adnotarea lipsește.
• Verificați Annotation.AnnotationType() înainte de a face casting sau ramificare pe comportamentul subtipului când iterați adnotările încărcate dintr-un fișier PDF neîncrezător sau de la terți.
• Aplatizați adnotările cu Annotation.Flatten() (sau PdfAnnotationEditor.FlatteningAnnotations() pentru întregul document) înainte de a arhiva un document, astfel încât recenzenții din alte instrumente să vadă aceeași prezentare pe care ați creat-o.
• AnnotationFlags este un bitfield — combinați steagurile cu valorile întregi de bază ale enumului în loc să presupuneți că doar un singur steag poate fi activ simultan.

Probleme comune

FAQ

Cum pot adăuga o adnotare de tip comentariu pe o pagină PDF?

Construiți un TextAnnotation cu ținta Document, setați-i Rect() și Contents(), apoi adăugați-l la page.Annotations() înainte de salvare.

Cum pot afla ce tip de adnotare privesc?

Apelă Annotation.AnnotationType(), care returnează o valoare enum AnnotationType cum ar fi Text, Link, Highlight, FreeText, FileAttachment sau Watermark.

Poate o adnotare să conțină mai multe steaguri?

Da. AnnotationFlags este un bitfield (Default, Invisible, Hidden, Print, NoZoom, ReadOnly, LockedContents și altele), astfel încât mai multe flaguri pot fi combinate într-o singură adnotare.

Care este diferența dintre a aplatiza o adnotare și a aplatiza un document?

Annotation.Flatten() îmbină o singură adnotare în conținutul paginii sale. PdfAnnotationEditor.FlatteningAnnotations() (opțional limitat prin interval de pagini și AnnotationType prin suprasarcina care acceptă start, end și annotType) aplatizează întregul document legat într-un singur apel.

Cum pot elimina toate adnotările de un anumit tip dintr-un document?

Leagă documentul cu PdfAnnotationEditor.BindPdf(), apelează DeleteAnnotations(annotType) cu AnnotationType țintă, apoi Save() rezultatul.

API Reference Rezumat

Vezi și:

• Aspose.PDF — Enterprise Documentation