Bekerja dengan Anotasi PDF

Bekerja dengan Anotasi PDF

Anotasi PDF dalam Aspose.PDF FOSS untuk C++ direpresentasikan oleh kelas dasar Annotation dan subtipe konkretnya (TextAnnotation, LinkAnnotation, HighlightAnnotation, FreeTextAnnotation, CircleAnnotation, WatermarkAnnotation, WidgetAnnotation, dan lainnya). Setiap halaman menyajikan anotasinya melalui Page.Annotations(), yang mengembalikan sebuah AnnotationCollection. Panduan ini mencakup penambahan anotasi ke halaman, iterasi dan penghapusan, membaca anotasi dari dokumen yang ada, melampirkan aksi tautan, menyesuaikan tampilan, dan meratakan anotasi.

Menambahkan Anotasi ke Halaman

Buat sebuah instance anotasi konkret, posisikan dengan Rectangle, dan tambahkan ke koleksi halaman dengan AnnotationCollection.Add(). TextAnnotation mewakili komentar bergaya catatan tempel yang terikat pada sebuah titik di halaman:

#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) mendapatkan dan mengatur teks catatan, dan Annotation.Rect() / Rect(value) memposisikan anotasi pada halaman.

Iterasi dan Penghapusan Anotasi

AnnotationCollection mendukung penghitungan, akses indeks, pemeriksaan keanggotaan, dan penghapusan berdasarkan nilai atau indeks:

#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) dan Remove(annotation) beroperasi pada referensi anotasi tertentu; Delete(index) menghapus berdasarkan posisi, dan Delete(annotation) menghapus anotasi spesifik tanpa memerlukan indeksnya. IsReadOnly() melaporkan apakah koleksi dapat dimodifikasi.

Membaca Anotasi dari Dokumen yang Ada

Ketika sebuah dokumen dimuat, anotasinya sudah terisi dan dapat diperiksa tanpa menambahkan apa pun. Annotation.AnnotationType() melaporkan subtipe (AnnotationType::Text, AnnotationType::Highlight, AnnotationType::Link, AnnotationType::FreeText, AnnotationType::FileAttachment, AnnotationType::Watermark, dan lainnya):

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

Urutan anotasi dan subtipe dipertahankan selama siklus simpan/muat kembali, sehingga kode yang mengindeks ke Annotations() setelah memuat dokumen melihat urutan yang sama seperti saat file ditulis.

Anotasi Tautan dan Aksi

LinkAnnotation menempelkan wilayah yang dapat diklik ke halaman dan mengirimkan PdfAction saat diaktifkan. NamedAction melompat ke target navigasi yang telah ditentukan, JavascriptAction menjalankan string ECMAScript, dan SubmitFormAction mengirim data formulir ke URL melalui 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) menerima subtipe PdfAction apa pun dan menggandakannya secara internal, sehingga anotasi mempertahankan salinan aksi miliknya sendiri. LinkAnnotation.Destination() / Destination(value) menetapkan target navigasi eksplisit alih-alih aksi, dan Highlighting() / Highlighting(value) mengontrol umpan balik visual yang ditampilkan saat tautan diklik.

Penampilan Anotasi: Garis Batas, Bendera, dan Warna

Setiap Annotation menampilkan Border, sebuah bitfield dari AnnotationFlags, dan Color yang digunakan untuk merender penampilannya:

#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() menerima BorderStyle::Solid, Dashed, Beveled, Inset, atau Underline. Border.Effect() juga mendukung sebuah outline BorderEffect::Cloudy dengan EffectIntensity() yang mengontrol seberapa menonjolnya. AnnotationFlags adalah bitfield — gabungkan nilai seperti Print, NoZoom, ReadOnly, dan LockedContents untuk mengontrol bagaimana anotasi berperilaku dalam penampil tanpa mengubah konten yang terlihat.

Meratakan Anotasi

Sebuah anotasi tunggal dapat diratakan — digabungkan ke dalam konten halaman dan dibuat non-interaktif — dengan memanggil Annotation.Flatten() secara langsung:

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

Untuk operasi anotasi pada seluruh dokumen, PdfAnnotationEditor mengikuti pola Facade bersama yang digunakan di seluruh API: mengikat dokumen sumber dengan BindPdf(), menerapkan satu atau lebih operasi anotasi, lalu menulis hasilnya dengan 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() menghapus semua anotasi dari dokumen yang terikat; DeleteAnnotations(annotType) membatasi penghapusan ke satu AnnotationType. ImportAnnotationsFromXfdf(xfdfFile) dan ImportAnnotationsFromFdf(fdfFile) memuat data anotasi yang diekspor dari penampil PDF lain.

Tips dan Praktik Terbaik

• Selalu tambahkan anotasi yang baru dibangun ke Page.Annotations() sebelum memanggil Document.Save() — anotasi yang tidak pernah ditambahkan ke koleksi tidak akan ditulis ke file output.
• Gunakan AnnotationCollection.Contains(annotation) sebelum memanggil Remove() jika Anda tidak yakin anotasi masih ada; Remove() mengembalikan false alih-alih melempar ketika anotasi tidak ada.
• Periksa Annotation.AnnotationType() sebelum melakukan casting atau percabangan berdasarkan perilaku subtipe saat mengiterasi anotasi yang dimuat dari file PDF yang tidak terpercaya atau pihak ketiga.
• Ratakan anotasi dengan Annotation.Flatten() (atau PdfAnnotationEditor.FlatteningAnnotations() untuk seluruh dokumen) sebelum mengarsipkan dokumen sehingga peninjau pada alat lain melihat tampilan yang sama seperti yang Anda buat.
• AnnotationFlags adalah bitfield — gabungkan flag dengan nilai integer dasar enum alih-alih mengasumsikan hanya satu flag yang dapat aktif pada satu waktu.

Masalah Umum

FAQ

Bagaimana cara menambahkan anotasi bergaya komentar ke halaman PDF?

Buat sebuah TextAnnotation dengan target Document, atur Rect() dan Contents()nya, lalu tambahkan ke page.Annotations() sebelum menyimpan.

Bagaimana saya mengetahui jenis anotasi apa yang sedang saya lihat?

Panggil Annotation.AnnotationType(), yang mengembalikan nilai enum AnnotationType seperti Text, Link, Highlight, FreeText, FileAttachment, atau Watermark.

Apakah satu anotasi dapat memiliki lebih dari satu flag?

Ya. AnnotationFlags adalah bitfield (Default, Invisible, Hidden, Print, NoZoom, ReadOnly, LockedContents, dan lainnya), sehingga beberapa flag dapat digabungkan pada satu anotasi.

Apa perbedaan antara meratakan satu anotasi dan meratakan sebuah dokumen?

Annotation.Flatten() menggabungkan satu anotasi ke dalam konten halamannya. PdfAnnotationEditor.FlatteningAnnotations() (secara opsional dibatasi oleh rentang halaman dan AnnotationType melalui overload yang menerima start, end, dan annotType) meratakan seluruh dokumen yang terikat dalam satu panggilan.

Bagaimana cara menghapus semua anotasi satu tipe dari dokumen?

Ikat dokumen dengan PdfAnnotationEditor.BindPdf(), panggil DeleteAnnotations(annotType) dengan target AnnotationType, lalu Save() hasilnya.

API Reference Ringkasan

Lihat Juga

• Aspose.PDF — Enterprise Documentation