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 panggilan Add*() — anotasi yang diperoleh dengan membaca ulang page.Annotations kemudian merupakan referensi objek yang berbeda.
  • SearchAnnotationText() dan SearchAnnotations() 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 /AP mereka secara otomatis — tidak diperlukan penggambaran aliran-konten manual.
  • Enkripsi tetap bertahan setelah siklus perjalanan: anotasi yang ditambahkan sebelum Document.Save() dengan opsi encrypt tetap valid setelah dokumen dibuka kembali dan didekripsi.

Masalah Umum

MasalahPenyebabPerbaikan
page.Annotations.find() mengembalikan undefined untuk anotasi yang baru saja Anda tambahkanMencari array usang yang diambil sebelum anotasi ditambahkanBaca 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 halamanTeks digambar oleh anotasi (misalnya tubuh FreeText), tidak dibawa dalam /ContentsGunakan 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/MetodeDeskripsi
AnnotationHandle dasar pada setiap anotasi; mengekspos Subtype, Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity
Annotation.Flatten()Menyematkan tampilan anotasi ke dalam konten halaman statis
TextAnnotationHandle catatan tempel /Text; menambahkan Icon, Open, Author
StampAnnotationHandle cap karet /Stamp; menambahkan StampName
MarkupAnnotationSebuah 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.AnnotationsSetiap Annotation pada halaman, sebagai array
Page.SearchAnnotationText()Temukan teks yang dibawa anotasi (/Contents, /T, /Subj)
Page.SearchAnnotations()Temukan teks yang digambar anotasi pada halaman

Lihat Juga

 Bahasa Indonesia