Arbeiten mit PDF-Anmerkungen

Arbeiten mit PDF-Anmerkungen

PDF-Anmerkungen in Aspose.PDF FOSS für C++ werden durch die Basisklasse Annotation und ihre konkreten Untertypen (TextAnnotation, LinkAnnotation, HighlightAnnotation, FreeTextAnnotation, CircleAnnotation, WatermarkAnnotation, WidgetAnnotation und weitere) repräsentiert. Jede Seite stellt ihre Anmerkungen über Page.Annotations() bereit, das ein AnnotationCollection zurückgibt. Dieser Leitfaden behandelt das Hinzufügen von Anmerkungen zu einer Seite, das Durchlaufen und Entfernen, das Lesen von Anmerkungen aus einem bestehenden Dokument, das Anfügen von Linkaktionen, das Anpassen des Erscheinungsbildes und das Flachlegen von Anmerkungen.

Hinzufügen von Anmerkungen zu einer Seite

Erstellen Sie eine konkrete Anmerkungsinstanz, positionieren Sie sie mit einem Rectangle und fügen Sie sie der Seitensammlung mit AnnotationCollection.Add() hinzu. TextAnnotation stellt einen klebezettelartigen Kommentar dar, der an einem Punkt auf der Seite verankert ist:

#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) lesen und setzen den Notiztext, und Annotation.Rect() / Rect(value) positionieren die Anmerkung auf der Seite.

Durchlaufen und Entfernen von Anmerkungen

AnnotationCollection unterstützt Zählen, indizierten Zugriff, Mitgliedschaftsprüfungen und das Entfernen nach Wert oder nach 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) und Remove(annotation) arbeiten mit einer bestimmten Annotationsreferenz; Delete(index) entfernt nach Position und Delete(annotation) entfernt eine bestimmte Annotation, ohne ihren Index zu benötigen. IsReadOnly() gibt an, ob die Sammlung modifiziert werden kann.

Anmerkungen aus einem bestehenden Dokument lesen

Wenn ein Dokument geladen wird, sind seine Anmerkungen bereits befüllt und können ohne Hinzufügen von etwas inspiziert werden. Annotation.AnnotationType() gibt den Subtyp an (AnnotationType::Text, AnnotationType::Highlight, AnnotationType::Link, AnnotationType::FreeText, AnnotationType::FileAttachment, AnnotationType::Watermark und weitere):

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

Die Reihenfolge und der Subtyp von Anmerkungen bleiben über einen Speicher-/Lade-Durchlauf erhalten, sodass Code, der nach dem Laden eines Dokuments in Annotations() indiziert, dieselbe Sequenz sieht, die beim Schreiben der Datei vorhanden war.

Link-Anmerkungen und Aktionen

LinkAnnotation fügt einer Seite einen anklickbaren Bereich hinzu und löst beim Aktivieren ein PdfAction aus. NamedAction springt zu einem vordefinierten Navigationsziel, JavascriptAction führt eine ECMAScript-Zeichenkette aus, und SubmitFormAction sendet Formulardaten an eine URL über ein 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) akzeptiert jeden PdfAction-Subtyp und klont ihn intern, sodass die Anmerkung ihre eigene Kopie der Aktion behält. LinkAnnotation.Destination() / Destination(value) setzen ein explizites Navigationsziel anstelle einer Aktion, und Highlighting() / Highlighting(value) steuern das visuelle Feedback, das beim Klicken auf den Link angezeigt wird.

Darstellung von Anmerkungen: Rahmen, Flags und Farbe

Jedes Annotation stellt ein Border, ein Bitfeld von AnnotationFlags, und ein Color zur Darstellung seines Erscheinungsbildes bereit:

#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() akzeptiert BorderStyle::Solid, Dashed, Beveled, Inset oder Underline. Border.Effect() unterstützt zusätzlich eine BorderEffect::Cloudy-Kontur mit EffectIntensity(), das steuert, wie ausgeprägt sie ist. AnnotationFlags ist ein Bitfeld – kombinieren Sie Werte wie Print, NoZoom, ReadOnly und LockedContents, um zu steuern, wie sich eine Anmerkung in einem Betrachter verhält, ohne ihren sichtbaren Inhalt zu ändern.

Flachlegen von Anmerkungen

Eine einzelne Anmerkung kann flachgelegt – in den Seiteninhalt integriert und nicht interaktiv gemacht – werden, indem Annotation.Flatten() direkt aufgerufen wird:

#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 dokumentweite Anmerkungsoperationen folgt PdfAnnotationEditor dem gemeinsamen Facade-Muster, das im gesamten API verwendet wird: Binden Sie ein Quelldokument mit BindPdf(), führen Sie ein oder mehrere Anmerkungsoperationen aus und schreiben Sie das Ergebnis mit 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() entfernt jede Anmerkung aus dem gebundenen Dokument; DeleteAnnotations(annotType) beschränkt das Entfernen auf eine einzelne AnnotationType. ImportAnnotationsFromXfdf(xfdfFile) und ImportAnnotationsFromFdf(fdfFile) laden Anmerkungsdaten, die von einem anderen PDF-Betrachter exportiert wurden.

Tipps und bewährte Verfahren

• Fügen Sie immer eine neu erstellte Anmerkung zu Page.Annotations() hinzu, bevor Sie Document.Save() aufrufen – eine Anmerkung, die nie zu einer Sammlung hinzugefügt wird, wird nicht in die Ausgabedatei geschrieben.
• Verwenden Sie AnnotationCollection.Contains(annotation) bevor Sie Remove() aufrufen, wenn Sie sich nicht sicher sind, dass die Anmerkung noch vorhanden ist; Remove() gibt false zurück, anstatt eine Ausnahme zu werfen, wenn die Anmerkung fehlt.
• Überprüfen Sie Annotation.AnnotationType(), bevor Sie beim Durchlaufen von Anmerkungen, die aus einer nicht vertrauenswürdigen oder Drittanbieter-PDF-Datei geladen wurden, einen Cast durchführen oder abhängig vom Subtyp-Verhalten verzweigen.
• Flachen Sie Anmerkungen mit Annotation.Flatten() (oder PdfAnnotationEditor.FlatteningAnnotations() für das gesamte Dokument) ab, bevor Sie ein Dokument archivieren, damit Prüfer in anderen Werkzeugen dieselbe von Ihnen erstellte Darstellung sehen.
• AnnotationFlags ist ein Bitfeld – kombinieren Sie Flags mit den zugrunde liegenden Ganzzahlwerten des Enums, anstatt anzunehmen, dass nur ein Flag gleichzeitig aktiv sein kann.

Häufige Probleme

FAQ

Wie füge ich einer PDF-Seite eine kommentarbezogene Anmerkung hinzu?

Erstellen Sie ein TextAnnotation mit dem Ziel-Document, setzen Sie dessen Rect() und Contents(), und fügen Sie es dann zu page.Annotations() hinzu, bevor Sie speichern.

Wie finde ich heraus, welche Art von Annotation ich betrachte?

Rufen Sie Annotation.AnnotationType() auf, das einen AnnotationType-Enum-Wert wie Text, Link, Highlight, FreeText, FileAttachment oder Watermark zurückgibt.

Kann eine Annotation mehr als ein Flag enthalten?

Ja. AnnotationFlags ist ein Bitfeld (Default, Invisible, Hidden, Print, NoZoom, ReadOnly, LockedContents und weitere), sodass mehrere Flags in einer einzelnen Annotation kombiniert werden können.

Was ist der Unterschied zwischen dem Flatten einer einzelnen Annotation und dem Flatten eines Dokuments?

Annotation.Flatten() fügt eine einzelne Annotation in den Inhalt ihrer Seite ein. PdfAnnotationEditor.FlatteningAnnotations() (optional auf einen Seitenbereich und AnnotationType über die Überladung, die start, end und annotType akzeptiert) flacht das gesamte gebundene Dokument in einem Aufruf ab.

Wie entferne ich alle Annotationen eines Typs aus einem Dokument?

Binden Sie das Dokument mit PdfAnnotationEditor.BindPdf(), rufen Sie DeleteAnnotations(annotType) mit dem Ziel AnnotationType auf und Save() Sie dann das Ergebnis.

API Reference Zusammenfassung

Siehe auch

• Aspose.PDF — Enterprise Documentation