Praca z adnotacjami PDF

Adnotacje PDF w Aspose.PDF FOSS dla C++ są reprezentowane przez klasę bazową Annotation oraz jej konkretne podtypy (TextAnnotation, LinkAnnotation, HighlightAnnotation, FreeTextAnnotation, CircleAnnotation, WatermarkAnnotation, WidgetAnnotation i inne). Każda strona udostępnia swoje adnotacje za pośrednictwem Page.Annotations(), które zwraca AnnotationCollection. Ten przewodnik obejmuje dodawanie adnotacji do strony, iterowanie i usuwanie ich, odczytywanie adnotacji z istniejącego dokumentu, dołączanie akcji linków, dostosowywanie wyglądu oraz spłaszczanie adnotacji.

Dodawanie adnotacji do strony

Utwórz konkretną instancję adnotacji, umieść ją za pomocą Rectangle i dodaj do kolekcji strony przy użyciu AnnotationCollection.Add(). TextAnnotation reprezentuje komentarz w stylu karteczki samoprzylepnej przypięty do punktu na stronie:

#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) pobierają i ustawiają tekst notatki, a Annotation.Rect() / Rect(value) pozycjonują adnotację na stronie.

Iterowanie i usuwanie adnotacji

AnnotationCollection obsługuje liczenie, dostęp indeksowy, sprawdzanie przynależności oraz usuwanie według wartości lub indeksu:

#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) działają na konkretnym odniesieniu do adnotacji; Delete(index) usuwa według pozycji, a Delete(annotation) usuwa określoną adnotację bez konieczności podawania jej indeksu. IsReadOnly() informuje, czy kolekcja może być modyfikowana.

Odczytywanie adnotacji z istniejącego dokumentu

Kiedy dokument zostaje załadowany, jego adnotacje są już wypełnione i można je przeglądać bez dodawania czegokolwiek. Annotation.AnnotationType() zgłasza podtyp (AnnotationType::Text, AnnotationType::Highlight, AnnotationType::Link, AnnotationType::FreeText, AnnotationType::FileAttachment, AnnotationType::Watermark i inne):

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

Kolejność adnotacji i podtyp są zachowywane przy zapisie/ponownym wczytaniu, więc kod indeksujący Annotations() po załadowaniu dokumentu widzi tę samą sekwencję, która była obecna w momencie zapisu pliku.

Adnotacje linków i akcje

LinkAnnotation dołącza klikalny obszar do strony i wyzwala PdfAction po aktywacji. NamedAction przeskakuje do zdefiniowanego wcześniej celu nawigacji, JavascriptAction uruchamia ciąg ECMAScript, a SubmitFormAction wysyła dane formularza pod adres URL za pomocą 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) akceptuje dowolny podtyp PdfAction i klonuje go wewnętrznie, dzięki czemu adnotacja zachowuje własną kopię akcji. LinkAnnotation.Destination() / Destination(value) ustawiają explicite cel nawigacji zamiast akcji, a Highlighting() / Highlighting(value) kontrolują wizualne informacje zwrotne wyświetlane podczas kliknięcia linku.

Wygląd adnotacji: obramowanie, flagi i kolor

Każdy Annotation udostępnia Border, bitową maskę AnnotationFlags oraz Color używaną do renderowania jego wyglądu:

#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() akceptuje BorderStyle::Solid, Dashed, Beveled, Inset lub Underline. Border.Effect() dodatkowo obsługuje kontur BorderEffect::Cloudy z EffectIntensity() kontrolującym, jak wyraźny jest. AnnotationFlags jest bitową maską — połącz wartości takie jak Print, NoZoom, ReadOnly i LockedContents, aby kontrolować zachowanie adnotacji w przeglądarce bez zmiany jej widocznej treści.

Spłaszczanie adnotacji

Pojedynczą adnotację można spłaszczyć — scalić z treścią strony i uczynić nieinteraktywną — wywołując bezpośrednio 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");
}

W przypadku operacji adnotacji obejmujących cały dokument, PdfAnnotationEditor stosuje współdzielony wzorzec Facade używany w całym API: powiąż dokument źródłowy przy pomocy BindPdf(), zastosuj jedną lub więcej operacji adnotacji, a następnie zapisz wynik przy użyciu 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() usuwa wszystkie adnotacje z powiązanego dokumentu; DeleteAnnotations(annotType) ogranicza usuwanie do jednej AnnotationType. ImportAnnotationsFromXfdf(xfdfFile) i ImportAnnotationsFromFdf(fdfFile) ładują dane adnotacji wyeksportowane z innej przeglądarki PDF.

Wskazówki i najlepsze praktyki

Zawsze dodawaj nowo utworzoną adnotację do Page.Annotations() przed wywołaniem Document.Save() — adnotacja, która nie zostanie dodana do kolekcji, nie zostanie zapisana w pliku wyjściowym.
Użyj AnnotationCollection.Contains(annotation) przed wywołaniem Remove(), jeśli nie masz pewności, że adnotacja nadal istnieje; Remove() zwraca false zamiast zgłaszać wyjątek, gdy adnotacja jest nieobecna.
Sprawdź Annotation.AnnotationType() przed rzutowaniem lub rozgałęzianiem się na podstawie zachowania podtypu podczas iteracji adnotacji załadowanych z niezaufanego lub zewnętrznego pliku PDF.
Spłaszcz adnotacje przy użyciu Annotation.Flatten() (lub PdfAnnotationEditor.FlatteningAnnotations() dla całego dokumentu) przed archiwizacją dokumentu, aby recenzenci korzystający z innych narzędzi widzieli taką samą wygląd, jaką stworzyłeś.
AnnotationFlags jest polem bitowym — łącz flagi z podstawowymi wartościami całkowitymi wyliczenia, zamiast zakładać, że jednocześnie może być aktywna tylko jedna flaga.

Typowe problemy

Problem	Przyczyna	Poprawka
Adnotacja nie jest widoczna po zapisaniu	Adnotacja została utworzona, ale nigdy nie została dodana do `Page.Annotations()`	Wywołaj `page.Annotations().Add(annotation)` przed `doc.Save()`
`Remove()` zwraca `false`	Przekazana referencja adnotacji nie odpowiada żadnemu wpisowi aktualnie znajdującemu się w kolekcji	Użyj `Contains()` najpierw lub usuń według indeksu przy użyciu `Delete(index)`
Nieprawidłowy typ adnotacji po przeładowaniu	Kod zakładał konkretny podtyp bez sprawdzania `AnnotationType()`	Rozgałęź się na `Annotation.AnnotationType()` przed traktowaniem obiektu jako konkretnego podtypu
Działanie linku wydaje się nieustawione po przypisaniu	Lokalny `PdfAction` wyszedł poza zakres; `LinkAnnotation.Action()` zwraca sklonowaną kopię adnotacji, a nie pierwotny obiekt	Odczytaj działanie ponownie przez `link.Action()`, zamiast trzymać oryginalną zmienną lokalną
Operacja `PdfAnnotationEditor` nie ma efektu	`BindPdf()` nie zostało wywołane, lub zostało wywołane ze ścieżką, która nie istnieje	Potwierdź, że `BindPdf()` zakończy się powodzeniem przed wywołaniem `FlatteningAnnotations()` lub `DeleteAnnotations()`

FAQ

Jak dodać adnotację w stylu komentarza do strony PDF?

Utwórz TextAnnotation z docelowym Document, ustaw jego Rect() i Contents(), a następnie dodaj go do page.Annotations() przed zapisaniem.

Jak mogę dowiedzieć się, jakiego rodzaju adnotację przeglądam?

Wywołaj Annotation.AnnotationType(), które zwraca wartość wyliczeniową AnnotationType, taką jak Text, Link, Highlight, FreeText, FileAttachment lub Watermark.

Czy jedna adnotacja może zawierać więcej niż jedną flagę?

Tak. AnnotationFlags jest polem bitowym (Default, Invisible, Hidden, Print, NoZoom, ReadOnly, LockedContents i inne), więc wiele flag może być łączonych w jednej adnotacji.

Jaka jest różnica między spłaszczaniem jednej adnotacji a spłaszczaniem dokumentu?

Annotation.Flatten() łączy pojedynczą adnotację z zawartością jej strony. PdfAnnotationEditor.FlatteningAnnotations() (opcjonalnie ograniczone zakresem stron i AnnotationType poprzez przeciążenie przyjmujące start, end i annotType) spłaszcza cały połączony dokument w jednym wywołaniu.

Jak usunąć wszystkie adnotacje jednego typu z dokumentu?

Zwiąż dokument z PdfAnnotationEditor.BindPdf(), wywołaj DeleteAnnotations(annotType) z docelowym AnnotationType, a następnie Save() wynik.

API Reference Podsumowanie

Klasa/Metoda	Opis
`Annotation`	Abstrakcyjna klasa bazowa dla wszystkich podtypów adnotacji PDF
`Annotation.Rect()` / `Rect(value)`	Pobierz lub ustaw prostokąt ograniczający adnotację
`Annotation.Contents()` / `Contents(value)`	Pobierz lub ustaw treść tekstową adnotacji
`Annotation.AnnotationType()`	Zwraca wartość `AnnotationType` enum dla tej adnotacji
`Annotation.Flags()` / `Flags(value)`	Pobierz lub ustaw pole bitowe `AnnotationFlags`
`Annotation.Border()` / `Border(value)`	Pobierz lub ustaw `Border` adnotacji
`Annotation.Color()` / `Color(value)`	Pobierz lub ustaw wyświetlanie adnotacji `Color`
`Annotation.Flatten()`	Łączy tę adnotację z treścią strony, czyniąc ją nieinteraktywną
`AnnotationCollection`	Uporządkowana kolekcja adnotacji na stronie, zwracana przez `Page.Annotations()`
`AnnotationCollection.Add(annotation)` / `Add(annotation, considerRotation)`	Dodaje adnotację do kolekcji
`AnnotationCollection.Count()`	Zwraca liczbę adnotacji w kolekcji
`AnnotationCollection.Contains(annotation)`	Raportuje, czy kolekcja zawiera podaną adnotację
`AnnotationCollection.Remove(annotation)`	Usuwa określoną adnotację; zwraca `false`, jeśli nie zostanie znaleziona
`AnnotationCollection.Delete(index)` / `Delete(annotation)`	Usuwa adnotację według indeksu lub odwołania
`AnnotationCollection.Clear()`	Usuwa wszystkie adnotacje z kolekcji
`TextAnnotation`	Adnotacja w stylu karteczki samoprzylepnej z `Open()` i `Icon()` (`TextIcon`)
`LinkAnnotation`	Obszar klikalny wysyłający `PdfAction` za pośrednictwem `Action()` / `Action(value)`
`LinkAnnotation.Destination()` / `Destination(value)`	Pobierz lub ustaw jawny cel nawigacji
`HighlightAnnotation`	Zaznacza fragment tekstu kolorem podświetlenia
`FreeTextAnnotation`	Wyświetla notatkę tekstową; konfigurowaną za pomocą `Justification()`, `DefaultAppearanceObject()`, `Callout()`
`CircleAnnotation`	Rysuje elipsę w prostokącie adnotacji
`WatermarkAnnotation`	Adnotacja nakładki z `Opacity()` / `Opacity(value)` accessor
`WidgetAnnotation`	Adnotacja wyglądu pola formularza z `ReadOnly()`, `Required()`, `Exportable()`, `DefaultAppearance()`
`NamedAction`	Predefiniowana akcja nawigacji (`PredefinedAction` enum) możliwa do dołączenia do `LinkAnnotation`
`JavascriptAction`	Uruchamia ciąg ECMAScript za pomocą `Script()` / `GetECMAScriptString()`
`SubmitFormAction`	Wysyła dane formularza do adresu URL `FileSpecification` za pomocą `Url()` / `Url(value)`
`Border`	Obramowanie adnotacji z `Width()`, `Style()` (`BorderStyle`), `Effect()` (`BorderEffect`)
`PdfAnnotationEditor`	Fasada do importu, modyfikacji, spłaszczania i usuwania adnotacji w całym dokumencie
`PdfAnnotationEditor.FlatteningAnnotations()`	Spłaszcza adnotacje w całym powiązanym dokumencie
`PdfAnnotationEditor.DeleteAnnotations(annotType)`	Usuwa wszystkie adnotacje danego `AnnotationType`
`PdfAnnotationEditor.ImportAnnotationsFromXfdf(xfdfFile)`	Importuje adnotacje z pliku XFDF

Zobacz także

Aspose.PDF — Enterprise Documentation