Arbeta med PDF-annotationer

Arbeta med PDF-annoteringar

PDF-annoteringar i Aspose.PDF FOSS för C++ representeras av bas-klassen Annotation och dess konkreta underklasser (TextAnnotation, LinkAnnotation, HighlightAnnotation, FreeTextAnnotation, CircleAnnotation, WatermarkAnnotation, WidgetAnnotation och andra). Varje sida exponerar sina annoteringar via Page.Annotations(), som returnerar en AnnotationCollection. Denna guide täcker att lägga till annoteringar på en sida, iterera och ta bort dem, läsa annoteringar från ett befintligt dokument, bifoga länkhändelser, anpassa utseende och platta till annoteringar.

Lägga till annoteringar på en sida

Skapa en konkret annoteringsinstans, placera den med en Rectangle, och lägg till den i sidans samling med AnnotationCollection.Add(). TextAnnotation representerar en klisterlappskommentar som är förankrad till en punkt på sidan:

#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) hämtar och anger nottexten, och Annotation.Rect() / Rect(value) placerar annoteringen på sidan.

Iterera och ta bort annoteringar

AnnotationCollection stödjer räknande, indexerad åtkomst, medlemskontroller och borttagning efter värde eller efter 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) och Remove(annotation) arbetar på en specifik annoteringsreferens; Delete(index) tar bort efter position, och Delete(annotation) tar bort en specifik annotering utan att behöva dess index. IsReadOnly() rapporterar om samlingen kan modifieras.

Läsa annoteringar från ett befintligt dokument

När ett dokument laddas är dess annoteringar redan fyllda och kan inspekteras utan att lägga till något. Annotation.AnnotationType() rapporterar subtypen (AnnotationType::Text, AnnotationType::Highlight, AnnotationType::Link, AnnotationType::FreeText, AnnotationType::FileAttachment, AnnotationType::Watermark och andra):

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

Annoteringsordning och subtyp bevaras över en spara/återläsningscykel, så kod som indexerar in i Annotations() efter att ett dokument har laddats ser samma sekvens som fanns när filen skrevs.

Länkanoteringar och åtgärder

LinkAnnotation fäster ett klickbart område på en sida och skickar en PdfAction när den aktiveras. NamedAction hoppar till ett fördefinierat navigeringsmål, JavascriptAction kör en ECMAScript-sträng, och SubmitFormAction postar formulärdata till en URL via en 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) accepterar vilken PdfAction subtyp som helst och klonar den internt, så att annoteringen behåller sin egen kopia av åtgärden. LinkAnnotation.Destination() / Destination(value) anger ett explicit navigeringsmål istället för en åtgärd, och Highlighting() / Highlighting(value) styr den visuella återkopplingen som visas när länken klickas.

Annoteringsutseende: kant, flaggor och färg

Varje Annotation exponerar en Border, ett bitfält av AnnotationFlags, och en Color som används för att rendera dess utseende:

#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() accepterar BorderStyle::Solid, Dashed, Beveled, Inset eller Underline. Border.Effect() stöder dessutom en BorderEffect::Cloudy kontur med EffectIntensity() som styr hur framträdande den är. AnnotationFlags är ett bitfält — kombinera värden såsom Print, NoZoom, ReadOnly och LockedContents för att kontrollera hur en annotation beter sig i en visare utan att ändra dess synliga innehåll.

Plattning av annotationer

En enskild annotation kan plattas till — slås samman med sidans innehåll och görs icke-interaktiv — genom att anropa Annotation.Flatten() direkt:

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

För dokumentomfattande annotation-operationer följer PdfAnnotationEditor det gemensamma Facade-mönstret som används över hela API: bind en källdokument med BindPdf(), utför en eller flera annotation-operationer och skriv sedan resultatet med 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() tar bort alla annotationer från det bundna dokumentet; DeleteAnnotations(annotType) begränsar borttagning till en enskild AnnotationType. ImportAnnotationsFromXfdf(xfdfFile) och ImportAnnotationsFromFdf(fdfFile) laddar annotationsdata som exporterats från en annan PDF-visare.

Tips och bästa praxis

• Lägg alltid till en nykonstruerad annotation i Page.Annotations() innan du anropar Document.Save() — en annotation som aldrig läggs till i en samling skrivs inte till utdatafilen.
• Använd AnnotationCollection.Contains(annotation) innan du anropar Remove() om du inte är säker på att annoteringen fortfarande finns; Remove() returnerar false istället för att kasta ett undantag när annoteringen saknas.
• Kontrollera Annotation.AnnotationType() innan du kastar eller förgrenar dig baserat på subtypbeteende när du itererar annoteringar som laddats från en opålitlig eller tredje parts PDF-fil.
• Platta till annoteringar med Annotation.Flatten() (eller PdfAnnotationEditor.FlatteningAnnotations() för hela dokumentet) innan du arkiverar ett dokument så att granskare i andra verktyg ser samma utseende som du skapat.
• AnnotationFlags är ett bitfält — kombinera flaggor med enumens underliggande heltalsvärden snarare än att anta att endast en flagga kan vara aktiv åt gången.

Vanliga problem

FAQ

Hur lägger jag till en kommentarliknande annotering på en PDF-sida?

Skapa en TextAnnotation med mål-Document, sätt dess Rect() och Contents(), och lägg sedan till den i page.Annotations() innan du sparar.

Hur kan jag ta reda på vilken typ av annotation jag tittar på?

Anropa Annotation.AnnotationType(), som returnerar ett AnnotationType enum-värde såsom Text, Link, Highlight, FreeText, FileAttachment eller Watermark.

Kan en annotation ha mer än en flagga?

Ja. AnnotationFlags är ett bitfält (Default, Invisible, Hidden, Print, NoZoom, ReadOnly, LockedContents och andra), så flera flaggor kan kombineras på en enskild annotation.

Vad är skillnaden mellan att platta till en annotation och att platta till ett dokument?

Annotation.Flatten() slår samman en enskild annotation med sidans innehåll. PdfAnnotationEditor.FlatteningAnnotations() (valfritt avgränsad av sidintervall och AnnotationType via den överlagrade versionen som accepterar start, end och annotType) plattar till hela det bundna dokumentet i ett anrop.

Hur tar jag bort alla annotationer av en viss typ från ett dokument?

Binda dokumentet med PdfAnnotationEditor.BindPdf(), anropa DeleteAnnotations(annotType) med mål-AnnotationType, och sedan Save() resultatet.

API Reference Sammanfattning

Se även

• Aspose.PDF — Enterprise Documentation