Annotations

คำอธิบายประกอบ

หน้านี้ครอบคลุมการสร้าง, การอ่าน, การค้นหา, และการทำให้แบน (flatten) คำอธิบายประกอบ PDF. Page เปิดเผยวิธี Add*() หนึ่งต่อแต่ละชนิดย่อยของคำอธิบายประกอบ, แต่ละวิธีจะคืนค่า handle Annotation ที่ใช้งานได้; คลาสฐาน Annotation และชนิดย่อยของมัน (TextAnnotation, StampAnnotation, MarkupAnnotation, และอื่น ๆ) เปิดเผยคุณสมบัติของคำอธิบายประกอบสำหรับการอ่านและแก้ไข.


การสร้างคำอธิบายประกอบ Markup, Note และ Link

สี่วิธีการทำเครื่องหมายข้อความ — Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly(), และ Page.AddStrikeOut() — รับอาร์เรย์ quads (/QuadPoints) และคืนค่า MarkupAnnotation. Page.AddLink() สร้างพื้นที่ที่คลิกได้พร้อม URI หรือการกระทำภายใน, และ Page.AddTextNote() เพิ่มไอคอนโน้ตแบบสติ๊กกี้ที่เปิดป๊อปอัพพร้อมข้อความ contents, คืนค่า 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 ยังเปิดเผยวิธีการสำหรับรูปทรงและการวาดอิสระ — AddSquare(), AddCircle(), AddLine(), AddPolygon(), AddPolyline(), AddInk(), AddFreeText(), AddCaret(), และ AddStamp() — แต่ละวิธีจะคืนค่า handle คำอธิบายประกอบที่สอดคล้องกับชนิดย่อยนั้น, สร้างลักษณะการแสดงผล /AP ของมันโดยอัตโนมัติ.


การอ่านและการแสดงรายการคำอธิบายประกอบ

page.Annotations คืออาร์เรย์ของทุก Annotation บนหน้า. คำอธิบายประกอบทุกตัว, ไม่ว่าจะเป็นชนิดย่อยใด, เปิดเผย Subtype, Rect, Color, Contents, Name, Layer, ModDate, Flags, Print, Hidden, และ Opacity; ชนิดย่อยจะเพิ่มฟิลด์ของตนเอง, เช่น StampAnnotation.StampName หรือ MarkupAnnotation.QuadPoints.

const freeText = page.Annotations.find((a) => a.Subtype === 'FreeText');
if (freeText) {
  freeText.Contents = 'Updated note text';
}

การค้นหาข้อความหมายเหตุ

Page.SearchAnnotationText() and Page.SearchAnnotations() ถูกตั้งใจให้แยกจากกัน. SearchAnnotationText() ค้นหาการตรงกันในข้อความและคำอธิบาย carries แทนที่จะวาด — ของโน้ต’s /Contents, ผู้เขียนของมัน (/T), หรือหัวข้อของมัน (/Subj) — และส่งคืน AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() ค้นหาการตรงกันในข้อความและคำอธิบาย draws, เช่น a FreeText’s คำที่มองเห็นได้, และคืนค่า 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');

การทำให้หมายเหตุแบน

Annotation.Flatten() ผสานลักษณะการแสดงผล /AP ของหมายเหตุโดยตรงลงในสตรีมเนื้อหาของหน้า ณ /Rect, แล้วลบออกจาก /Annots. ผลลัพธ์คือเนื้อหาถาวรและคงที่ — ไม่ใช่หมายเหตุที่แยกจากกันซึ่งผู้ดูสามารถคลิก, แก้ไข หรือซ่อนได้อีกต่อไป.

const note = page.AddTextNote({
  rect: [72, 660, 92, 680], icon: 'Comment', contents: 'Reviewed and approved.',
});
note.Flatten();

เคล็ดลับและแนวปฏิบัติที่ดีที่สุด

  • เรียก Flatten() บนวัตถุที่ส่งกลับโดยตรงจากการเรียก Add*() — หมายเหตุที่ได้จากการอ่าน page.Annotations ใหม่ภายหลังเป็นอ้างอิงวัตถุที่ต่างกัน.
  • SearchAnnotationText() และ SearchAnnotations() ครอบคลุมข้อความที่แตกต่างกัน: ให้รันทั้งสองหากคุณต้องการค้นหาวลีโดยไม่สนใจว่ามันถูกพิมพ์ลงในโน้ตหรือวาดบนหน้า.
  • สี่วิธีการทำเครื่องหมาย (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut) สร้างลักษณะการแสดงผล /AP ของพวกมันโดยอัตโนมัติ — ไม่จำเป็นต้องวาดสตรีมเนื้อหาแบบมือ.
  • การเข้ารหัสยังคงอยู่หลังการเดินทางรอบหนึ่ง: คำอธิบายที่เพิ่มก่อน Document.Save() ด้วยตัวเลือก encrypt จะยังคงใช้ได้หลังจากเปิดเอกสารใหม่และถอดรหัส.

ปัญหาที่พบบ่อย

ปัญหาสาเหตุแก้ไข
page.Annotations.find() คืนค่า undefined สำหรับคำอธิบายที่คุณเพิ่งเพิ่มกำลังค้นหาอาเรย์ที่ล้าสมัยซึ่งถูกจับไว้ก่อนที่คำอธิบายจะถูกเพิ่มอ่าน page.Annotations ใหม่หลังจากการเรียก Add*(), หรือใช้ตัวจัดการที่การเรียกคืนค่าโดยตรง
SearchAnnotationText() ไม่พบอะไรสำหรับข้อความที่มองเห็นบนหน้าข้อความถูกวาดโดยคำอธิบาย (เช่น เนื้อหาของ FreeText), ไม่ได้ถูกบรรจุใน /Contentsใช้ SearchAnnotations() แทน — มันตรงกับข้อความที่วาด
คำอธิบายยังคงแสดงว่าแก้ไขได้หลังจาก Flatten()Flatten() ถูกเรียกบนสำเนาแทนที่จะเป็นตัวจัดการที่ Add*() ส่งคืนเรียก Flatten() บนวัตถุที่ส่งคืนโดยตรงจากเมธอดการสร้าง

FAQ

ความแตกต่างระหว่าง SearchAnnotationText กับ SearchAnnotations คืออะไร?

SearchAnnotationText() ตรงกับข้อความของคำอธิบาย carries — /Contents, /T (author), หรือ /Subj — เช่น เนื้อหาของสติ๊กกี้โน้ต. SearchAnnotations() จับคู่ข้อความกับคำอธิบาย draws บนหน้า, เช่น FreeTextคำที่มองเห็นได้ของ ’s. ทั้งสองเป็นส่วนที่แยกกัน: การจับคู่ในหนึ่งจะไม่ปรากฏในอีกอันหนึ่ง.

ฉันจะทำให้คำอธิบายเป็นถาวรและไม่โต้ตอบได้อย่างไร?

เรียก Flatten() บน Annotation handle ที่คืนค่ามาจากเมธอด Add*() ที่สร้างมัน. วิธีนี้จะฝังลักษณะการแสดงผลของมันลงในสตรีมเนื้อหาของหน้าและลบออกจาก /Annots.

รองรับประเภทย่อยของคำอธิบายใดบ้าง?

Page เปิดเผยวิธีการสร้างสำหรับการทำเครื่องหมายข้อความ (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut), บันทึกและการอ้างอิง (AddTextNote, AddFreeText, AddCaret), ลิงก์ (AddLink), รูปร่าง (AddSquare, AddCircle, AddLine, AddPolygon, AddPolyline), หมึกวาดด้วยมือ (AddInk), ตราประทับ (AddStamp), และไฟล์แนบ (AddFileAttachment).

ฉันจะทำรายการคำอธิบายทั้งหมดที่มีอยู่บนหน้าอย่างไร?

อ่าน page.Annotations, ซึ่งเป็นอาเรย์ของตัวจัดการ Annotation. แต่ละตัวเปิดเผย Subtype, Rect, Color, Contents, และคุณสมบัติที่ใช้ร่วมกันอื่น ๆ, ดังนั้นคุณสามารถกรองหรือสำรวจพวกมันด้วยเมธอดอาเรย์มาตรฐานได้.


API Reference สรุป

คลาส/เมธอดคำอธิบาย
AnnotationBase handle over any annotation; เปิดเผย Subtype, Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity
Annotation.Flatten()ใส่ลักษณะของคำอธิบายลงในเนื้อหาหน้าคงที่
TextAnnotationตัวจัดการ sticky-note /Text ; เพิ่ม Icon, Open, Author
StampAnnotationตัวจัดการ rubber-stamp /Stamp ; เพิ่ม StampName
MarkupAnnotationตัวจัดการ text-markup (Highlight/Underline/StrikeOut/Squiggly) ; เพิ่ม MarkupType, QuadPoints
Page.AddHighlight() / Page.AddUnderline() / Page.AddStrikeOut() / Page.AddSquiggly()สร้างหมายเหตุ text-markup บน /QuadPoints
Page.AddTextNote()สร้างบันทึกย่อแบบสติ๊กกี้
Page.AddLink()สร้างลิงก์ที่คลิกได้พร้อม URI หรือการกระทำภายใน
Page.Annotationsทุก Annotation บนหน้าเป็นอาเรย์
Page.SearchAnnotationText()ค้นหาข้อความที่คำอธิบายมี (/Contents, /T, /Subj)
Page.SearchAnnotations()ค้นหาข้อความที่คำอธิบายวาดบนหน้า

ดูเพิ่มเติม

 ภาษาไทย