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 สรุป
| คลาส/เมธอด | คำอธิบาย |
|---|---|
Annotation | Base 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() | ค้นหาข้อความที่คำอธิบายวาดบนหน้า |