Annotations
Anotasi
Halaman ini mencakup pembuatan, pembacaan, pencarian, dan pelurusan anotasi PDF. Page mengekspos satu metode Add*() per subtipe anotasi, masing-masing mengembalikan handle Annotation yang aktif; kelas dasar Annotation dan subtipe-subtipenya (TextAnnotation, StampAnnotation, MarkupAnnotation, dan lainnya) mengekspos properti anotasi untuk dibaca dan diedit.
Membuat Anotasi Markup, Catatan, dan Tautan
Empat metode markup teks — Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly(), dan Page.AddStrikeOut() — menerima array quads (/QuadPoints) dan mengembalikan MarkupAnnotation. Page.AddLink() membuat wilayah yang dapat diklik dengan URI atau aksi internal, dan Page.AddTextNote() menambahkan ikon catatan tempel yang membuka popup dengan teks contents, mengembalikan TextAnnotation.
page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' });
page.AddUnderline({ quads, color: [0, 0, 1] });
page.AddStrikeOut({ quads, color: [1, 0, 0] });
page.AddLink({
rect: [100, 700, 220, 716],
action: { type: 'uri', uri: 'https://example.com' },
border: 0,
});
page.AddTextNote({
rect: [x, y, x + 20, y + 20], icon: 'Note', author: 'Reviewer',
contents: 'This is a sticky-note annotation.',
});Page juga mengekspos metode bentuk dan tangan bebas — AddSquare(), AddCircle(), AddLine(), AddPolygon(), AddPolyline(), AddInk(), AddFreeText(), AddCaret(), dan AddStamp() — masing-masing mengembalikan handle anotasi yang sesuai untuk subtipe tersebut, menghasilkan penampilan /AP secara otomatis.
Membaca dan Mendaftar Anotasi
page.Annotations adalah array dari setiap Annotation pada halaman. Setiap anotasi, terlepas dari subtipe, mengekspos Subtype, Rect, Color, Contents, Name, Layer, ModDate, Flags, Print, Hidden, dan Opacity; subtipe menambahkan bidang mereka sendiri, seperti StampAnnotation.StampName atau MarkupAnnotation.QuadPoints.
const freeText = page.Annotations.find((a) => a.Subtype === 'FreeText');
if (freeText) {
freeText.Contents = 'Updated note text';
}Mencari Teks Anotasi
Page.SearchAnnotationText() and Page.SearchAnnotations() secara sengaja tidak berhubungan. SearchAnnotationText() menemukan kecocokan dalam teks dan anotasi carries daripada menggambar — milik catatan /Contents, penulisnya (/T), atau subjeknya (/Subj) — dan mengembalikan AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() menemukan kecocokan dalam teks dan anotasi draws, seperti sebuah FreeText’s kata yang terlihat, dan mengembalikan AnnotationMatch[] ({ annot, text, quads }).
// A sticky note's /Contents text — found by SearchAnnotationText, not SearchAnnotations.
const textHits = page.SearchAnnotationText('body secret');
console.log(textHits[0].key, textHits[0].value); // 'Contents' 'body secret'
// A FreeText's rendered words — found by SearchAnnotations, not SearchAnnotationText.
const drawnHits = page.SearchAnnotations('bravo');Meratakan Anotasi
Annotation.Flatten() menyematkan tampilan /AP anotasi langsung ke dalam aliran konten halaman pada /Rect, lalu menghapusnya dari /Annots. Hasilnya adalah konten permanen dan statis — tidak lagi menjadi anotasi terpisah yang dapat diklik, diedit, atau disembunyikan oleh penonton.
const note = page.AddTextNote({
rect: [72, 660, 92, 680], icon: 'Comment', contents: 'Reviewed and approved.',
});
note.Flatten();Tips dan Praktik Terbaik
- Panggil
Flatten()pada objek yang dikembalikan langsung oleh panggilanAdd*()— anotasi yang diperoleh dengan membaca ulangpage.Annotationskemudian merupakan referensi objek yang berbeda. SearchAnnotationText()danSearchAnnotations()mencakup teks yang berbeda: jalankan keduanya jika Anda perlu menemukan frasa terlepas dari apakah itu diketik dalam catatan atau digambar pada halaman.- Keempat metode markup (
AddHighlight,AddUnderline,AddSquiggly,AddStrikeOut) menghasilkan tampilan/APmereka secara otomatis — tidak diperlukan penggambaran aliran-konten manual. - Enkripsi tetap bertahan setelah siklus perjalanan: anotasi yang ditambahkan sebelum
Document.Save()dengan opsiencrypttetap valid setelah dokumen dibuka kembali dan didekripsi.
Masalah Umum
| Masalah | Penyebab | Perbaikan |
|---|---|---|
page.Annotations.find() mengembalikan undefined untuk anotasi yang baru saja Anda tambahkan | Mencari array usang yang diambil sebelum anotasi ditambahkan | Baca ulang page.Annotations setelah pemanggilan Add*(), atau gunakan handle yang dikembalikan oleh pemanggilan tersebut secara langsung |
SearchAnnotationText() tidak menemukan apa pun untuk teks yang terlihat di halaman | Teks digambar oleh anotasi (misalnya tubuh FreeText), tidak dibawa dalam /Contents | Gunakan SearchAnnotations() sebagai gantinya — itu cocok dengan teks yang digambar |
Anotasi masih muncul dapat diedit setelah Flatten() | Flatten() dipanggil pada salinan alih-alih pegangan yang dikembalikan Add*() | Panggil Flatten() pada objek yang dikembalikan langsung oleh metode pembuatannya |
FAQ
Apa perbedaan antara SearchAnnotationText dan SearchAnnotations?
SearchAnnotationText() mencocokkan teks sebuah anotasi carries — /Contents, /T (penulis), atau /Subj — seperti isi catatan tempel. SearchAnnotations() mencocokkan teks sebuah anotasi draws di halaman, seperti sebuah FreeText’s kata yang terlihat. Kedua bersifat terpisah: sebuah kecocokan di satu tidak akan muncul di yang lain.
Bagaimana cara menjadikan anotasi permanen dan tidak interaktif?
Panggil Flatten() pada handle Annotation yang dikembalikan oleh metode Add*() yang membuatnya. Ini menanamkan tampilannya ke dalam aliran konten halaman dan menghapusnya dari /Annots.
Subtipe anotasi mana yang didukung?
Page menyediakan metode pembuatan untuk markup teks (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut), catatan dan panggilan (AddTextNote, AddFreeText, AddCaret), tautan (AddLink), bentuk (AddSquare, AddCircle, AddLine, AddPolygon, AddPolyline), tinta bebas (AddInk), stempel (AddStamp), dan lampiran file (AddFileAttachment).
Bagaimana cara saya menampilkan semua anotasi yang sudah ada di halaman?
Baca page.Annotations, sebuah array dari handle Annotation. Setiapnya menyediakan Subtype, Rect, Color, Contents, dan properti bersama lainnya, sehingga Anda dapat memfilter atau memeriksanya dengan metode array standar.
API Reference Ringkasan
| Kelas/Metode | Deskripsi |
|---|---|
Annotation | Handle dasar pada setiap anotasi; mengekspos Subtype, Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity |
Annotation.Flatten() | Menyematkan tampilan anotasi ke dalam konten halaman statis |
TextAnnotation | Handle catatan tempel /Text; menambahkan Icon, Open, Author |
StampAnnotation | Handle cap karet /Stamp; menambahkan StampName |
MarkupAnnotation | Sebuah handle text-markup (Highlight/Underline/StrikeOut/Squiggly); menambahkan MarkupType, QuadPoints |
Page.AddHighlight() / Page.AddUnderline() / Page.AddStrikeOut() / Page.AddSquiggly() | Buat anotasi text-markup pada /QuadPoints |
Page.AddTextNote() | Buat anotasi catatan tempel |
Page.AddLink() | Buat tautan yang dapat diklik dengan URI atau aksi internal |
Page.Annotations | Setiap Annotation pada halaman, sebagai array |
Page.SearchAnnotationText() | Temukan teks yang dibawa anotasi (/Contents, /T, /Subj) |
Page.SearchAnnotations() | Temukan teks yang digambar anotasi pada halaman |