Werken met PDF-annotaties

Werken met PDF-annotaties

PDF-annotaties in Aspose.PDF FOSS voor C++ worden weergegeven door de Annotation basisklasse en zijn concrete subtypes (TextAnnotation, LinkAnnotation, HighlightAnnotation, FreeTextAnnotation, CircleAnnotation, WatermarkAnnotation, WidgetAnnotation en andere). Elke pagina stelt zijn annotaties beschikbaar via Page.Annotations(), die een AnnotationCollection retourneert. Deze gids behandelt het toevoegen van annotaties aan een pagina, itereren en verwijderen ervan, het lezen van annotaties uit een bestaand document, het koppelen van linkacties, het aanpassen van het uiterlijk en het platmaken van annotaties.

Annotaties toevoegen aan een pagina

Maak een concrete annotatie-instantie, positioneer deze met een Rectangle, en voeg deze toe aan de collectie van de pagina met AnnotationCollection.Add(). TextAnnotation staat voor een plakkerige-notitie-stijl commentaar verankerd op een punt op de pagina:

#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) halen en zetten de notitietekst, en Annotation.Rect() / Rect(value) positioneren de annotatie op de pagina.

Itereren en annotaties verwijderen

AnnotationCollection ondersteunt tellen, geïndexeerde toegang, lidmaatschapscontroles en verwijdering op waarde of op 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) en Remove(annotation) werken op een specifieke annotatiereferentie; Delete(index) verwijdert op positie, en Delete(annotation) verwijdert een specifieke annotatie zonder de index te hoeven kennen. IsReadOnly() meldt of de collectie kan worden aangepast.

Annotaties lezen uit een bestaand document

Wanneer een document wordt geladen, zijn de annotaties al gevuld en kunnen ze worden geïnspecteerd zonder iets toe te voegen. Annotation.AnnotationType() meldt het subtype (AnnotationType::Text, AnnotationType::Highlight, AnnotationType::Link, AnnotationType::FreeText, AnnotationType::FileAttachment, AnnotationType::Watermark, en anderen):

#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";
        }
    }
}

De volgorde en het subtype van annotaties worden behouden tijdens een opslaan/herladen cyclus, zodat code die na het laden van een document indexeert in Annotations() dezelfde reeks ziet als die aanwezig was toen het bestand werd geschreven.

Linkannotaties en acties

LinkAnnotation voegt een klikbaar gebied toe aan een pagina en stuurt een PdfAction uit wanneer geactiveerd. NamedAction springt naar een vooraf gedefinieerd navigatiedoel, JavascriptAction voert een ECMAScript-string uit, en SubmitFormAction post formulierdata naar een URL via een 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) accepteert elk PdfAction subtype en kloont het intern, zodat de annotatie zijn eigen kopie van de actie behoudt. LinkAnnotation.Destination() / Destination(value) stellen een expliciet navigatiedoel in plaats van een actie in, en Highlighting() / Highlighting(value) regelen de visuele feedback die wordt getoond terwijl de link wordt aangeklikt.

Uiterlijk van annotatie: rand, vlaggen en kleur

Elke Annotation geeft een Border bloot, een bitveld van AnnotationFlags, en een Color die wordt gebruikt om zijn uiterlijk weer te geven:

#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() accepteert BorderStyle::Solid, Dashed, Beveled, Inset of Underline. Border.Effect() ondersteunt bovendien een BorderEffect::Cloudy omtrek met EffectIntensity() die bepaalt hoe uitgesproken deze is. AnnotationFlags is een bitveld — combineer waarden zoals Print, NoZoom, ReadOnly en LockedContents om te bepalen hoe een annotatie zich gedraagt in een viewer zonder de zichtbare inhoud te wijzigen.

Annotaties flattenen

Een enkele annotatie kan worden geflatten — samengevoegd met de paginainhoud en niet-interactief gemaakt — door rechtstreeks Annotation.Flatten() aan te roepen:

#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");
}

Voor documentbrede annotatie-bewerkingen volgt PdfAnnotationEditor het gedeelde Facade-patroon dat wordt gebruikt in de API: koppel een brondocument met BindPdf(), voer één of meer annotatie-bewerkingen uit, en schrijf vervolgens het resultaat weg met 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() verwijdert elke annotatie uit het gekoppelde document; DeleteAnnotations(annotType) beperkt de verwijdering tot één AnnotationType. ImportAnnotationsFromXfdf(xfdfFile) en ImportAnnotationsFromFdf(fdfFile) laden annotatiegegevens die zijn geëxporteerd vanuit een andere PDF-viewer.

Tips en best practices

• Voeg altijd een nieuw geconstrueerde annotatie toe aan Page.Annotations() voordat je Document.Save() aanroept — een annotatie die nooit aan een collectie wordt toegevoegd, wordt niet weggeschreven naar het output-bestand.
• Gebruik AnnotationCollection.Contains(annotation) voordat je Remove() aanroept als je niet zeker bent dat de annotatie nog aanwezig is; Remove() retourneert false in plaats van een uitzondering te gooien wanneer de annotatie afwezig is.
• Controleer Annotation.AnnotationType() voordat je cast of vertakt op subtype-gedrag bij het itereren over annotaties die geladen zijn uit een onbetrouwbaar of extern PDF-bestand.
• Vlak annotaties af met Annotation.Flatten() (of PdfAnnotationEditor.FlatteningAnnotations() voor het hele document) voordat je een document archiveert, zodat reviewers in andere tools dezelfde weergave zien die jij hebt gemaakt.
• AnnotationFlags is een bitveld — combineer vlaggen met de onderliggende gehele getalwaarde van de enum in plaats van aan te nemen dat er slechts één vlag tegelijk actief kan zijn.

Veelvoorkomende problemen

FAQ

Hoe voeg ik een commentaar-stijl annotatie toe aan een PDF-pagina?

Construeer een TextAnnotation met het doel Document, stel zijn Rect() en Contents() in, en voeg het vervolgens toe aan page.Annotations() voordat je opslaat.

Hoe kom ik erachter welk type annotatie ik bekijk?

Roep Annotation.AnnotationType() aan, die een AnnotationType enum-waarde retourneert, zoals Text, Link, Highlight, FreeText, FileAttachment of Watermark.

Kan één annotatie meer dan één vlag bevatten?

Ja. AnnotationFlags is een bitveld (Default, Invisible, Hidden, Print, NoZoom, ReadOnly, LockedContents en anderen), dus kunnen meerdere vlaggen op één annotatie worden gecombineerd.

Wat is het verschil tussen het flattenen van één annotatie en het flattenen van een document?

Annotation.Flatten() voegt een enkele annotatie samen met de inhoud van de pagina. PdfAnnotationEditor.FlatteningAnnotations() (optioneel beperkt tot een paginabereik en AnnotationType via de overload die start, end en annotType accepteert) flatten het gehele gebonden document in één oproep.

Hoe verwijder ik alle annotaties van één type uit een document?

Bind het document met PdfAnnotationEditor.BindPdf(), roep DeleteAnnotations(annotType) aan met het doel AnnotationType, en Save() vervolgens het resultaat.

API Reference Samenvatting

Zie ook

• Aspose.PDF — Enterprise Documentation