Anotasi PDF

Anotasi PDF

Page.annotations mengekspos sebuah AnnotationCollection — tampilan yang dapat diubah, mirip urutan, atas setiap anotasi pada halaman. Setiap entri adalah Annotation (atau subclass MarkupAnnotation / LinkAnnotation), dan data spesifik subtipe seperti titik kuad, daftar tinta, atau warna dibaca dan ditulis melalui get_property() / set_property() alih-alih atribut khusus.

Menambahkan Anotasi

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) membuat anotasi baru dan menambahkannya ke halaman. subtype menerima baik string biasa ("Text", "Square", "Highlight") atau anggota enum AnnotationType.

import aspose_pdf
from aspose_pdf import Document, AnnotationType

doc = Document()
doc.pages.add()
page = doc.pages[0]

# Plain string subtype
page.annotations.add("Text", (100, 100, 200, 200), "Hello")

# AnnotationType enum, with subtype-specific properties
page.annotations.add(
    AnnotationType.POLYGON,
    (0, 0, 10, 10),
    "",
    properties={"Vertices": [0, 0, 10, 0, 5, 10]},
)

Membaca dan Memperbarui Properti

get_property(name, default) membaca nilai spesifik subtipe; set_property(name, value) menulis satu, dan mengatur properti menjadi None menghapusnya dari kamus properties anotasi.

doc = Document()
doc.pages.add()
page = doc.pages[0]

ann = page.annotations.add(
    "Square", (0, 0, 50, 50), "x", properties={"C": [1, 0, 0]},
)
ann.set_property("IC", [0, 0, 1])
print(page.annotations[0].get_property("IC"))  # [0, 0, 1]

ann.set_property("C", None)  # removes the "C" entry entirely
print("C" in page.annotations[0].properties)  # False

Menamai Anotasi dengan AnnotationName

Nama PDF (misalnya entri Name anotasi Stamp) ditandai secara berbeda dari string biasa menggunakan AnnotationName, subclass str dari aspose_pdf.engine.cos. Nilai yang disimpan dengan cara ini masih dibandingkan sama dengan string biasa.

from aspose_pdf.engine.cos import AnnotationName

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add(
    "Stamp", (10, 10, 110, 60), "",
    properties={"Name": AnnotationName("Approved")},
)

Menyisipkan, Menghapus, dan Mengosongkan

insert(index, subtype, rect, contents, title, appearance_normal, properties) menempatkan anotasi baru pada posisi tertentu; delete(index) menghapus satu berdasarkan indeks (menimbulkan IndexError untuk indeks di luar jangkauan); clear() menghapus semua anotasi dari halaman.

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add("Text", (0, 0, 100, 100), "A")
page.annotations.add("Text", (200, 200, 300, 300), "C")
page.annotations.insert(1, "Text", (100, 100, 200, 200), "B")
# order is now: A, B, C

page.annotations.delete(1)   # removes "B"
page.annotations.clear()     # removes everything remaining

Menghasilkan Tampilan Anotasi

Annotation.generate_appearance(force) membangun aliran tampilan /AP /N untuk satu anotasi dan mengembalikan True ketika ada perender untuk subtipe tersebut; AnnotationCollection.generate_appearances(force) melakukan hal yang sama untuk setiap anotasi pada halaman dalam satu panggilan dan mengembalikan jumlah anotasi yang memang dihasilkan (subtipe yang tidak didukung dilewati).

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add("Square", (0, 0, 50, 50), "")
page.annotations.add("Circle", (60, 0, 110, 50), "")
page.annotations.add("Text", (0, 60, 20, 80), "")  # unsupported subtype -> skipped

generated = page.annotations.generate_appearances()
print(generated)  # 2

Subtipe Anotasi dan Flags

AnnotationType mendaftar nama subtipe standar PDF 32000-1:2008 (Tabel 169): TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, POLY_LINE, HIGHLIGHT, UNDERLINE, SQUIGGLY, STRIKE_OUT, STAMP, CARET, INK, POPUP, FILE_ATTACHMENT, SOUND, MOVIE, WIDGET, SCREEN, PRINTER_MARK, TRAP_NET, WATERMARK, dan REDACT.

AnnotationFlags adalah IntFlag yang mencakup perilaku tampilan/interaksi anotasi: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED, dan TOGGLE_NO_VIEW.

Pra-rilis: Anotasi 3D

PDF3DAnnotation, PDF3DArtwork, PDF3DContent, dan PDF3DView memodelkan karya seni 3D yang terlampir pada sebuah halaman — sebuah PDF3DAnnotation memiliki rect: Rectangle, sebuah artwork: PDF3DArtwork, dan background_color: Color opsional. PDF3DArtwork.add_view() mendaftarkan sebuah PDF3DView, masing-masing membawa sebuah render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) dan sebuah lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM). Docstring perpustakaan sendiri menandai PDF3DAnnotation sebagai “minimal annotation wrapper for prerelease imports” — perlakukan permukaan ini sebagai tahap awal bukan sebagai API authoring 3D yang sudah selesai penuh.

Tips dan Praktik Terbaik

• Lebih pilih anggota enum AnnotationType daripada string subtype mentah ketika nilai tersebut juga perlu dibandingkan atau dijadikan cabang di tempat lain dalam kode Anda.
• Panggil set_property(name, None) untuk menghapus properti secara langsung daripada membiarkan nilai usang tetap ada — entri tersebut menghilang dari properties sepenuhnya.
• Buat generasi tampilan secara batch dengan AnnotationCollection.generate_appearances alih-alih melakukan loop generate_appearance() per anotasi; fungsi ini mengembalikan jumlah sebenarnya yang dihasilkan sehingga Anda dapat mendeteksi subtipe yang dilewatkan/tidak didukung.
• delete() dan pengindeksan ke page.annotations keduanya berbasis 0; validasi indeks sebelum memanggil delete() jika berasal dari input pengguna, karena indeks di luar jangkauan akan memicu IndexError.
• Bungkus nilai nama PDF (seperti Name milik Stamp) dalam AnnotationName sehingga mereka dipertahankan sebagai nama PDF alih-alih string teks biasa.

Masalah Umum

FAQ

Bagaimana cara menambahkan anotasi komentar teks biasa?

Panggil page.annotations.add("Text", (x0, y0, x1, y1), "comment text"). Tuple empat angka adalah persegi panjang anotasi pada halaman.

Apa perbedaan antara Annotation, MarkupAnnotation, dan LinkAnnotation?

Annotation adalah tampilan langsung yang dikembalikan untuk setiap anotasi pada halaman. MarkupAnnotation adalah dasar untuk subtipe gaya markup (penyorotan, catatan teks, bentuk) dan LinkAnnotation dipertahankan untuk anotasi gaya tautan; keduanya saat ini menampilkan permukaan metode/properti yang sama seperti Annotation.

Apakah saya dapat menghapus satu properti tanpa menghapus seluruh anotasi?

Ya — panggil annotation.set_property(name, None); anotasi itu sendiri tidak diubah, hanya entri tersebut yang dihapus dari properties.

Apakah AnnotationCollection.generate_appearances gagal jika subtipe tidak didukung?

Tidak. Ia melewati subtipe yang tidak memiliki renderer tampilan bawaan dan mengembalikan jumlah anotasi yang sebenarnya ia hasilkan tampilan untuknya.

Apakah kelas anotasi 3D siap untuk produksi?

PDF3DAnnotation dan tipe terkait didokumentasikan sebagai pembungkus minimal untuk impor pra-rilis — verifikasi perilaku terhadap penampil PDF target Anda sebelum mengandalkannya untuk konten 3D produksi.

API Reference Ringkasan

Lihat Juga

• Aspose.PDF for Python — Enterprise Documentation