คำอธิบาย PDF

หมายเหตุ PDF

Page.annotations เปิดเผย AnnotationCollection — มุมมองที่เปลี่ยนแปลงได้และคล้ายลำดับของหมายเหตุทั้งหมดบนหน้าแต่ละหน้า แต่ละรายการเป็น Annotation (หรือคลาสย่อย MarkupAnnotation / LinkAnnotation) และข้อมูลที่เฉพาะตามชนิดย่อย เช่น จุดสี่เหลี่ยม, รายการหมึก, หรือสี จะถูกอ่านและเขียนผ่าน get_property() / set_property() แทนการใช้แอตทริบิวต์เฉพาะ.

การเพิ่มหมายเหตุ

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) สร้างหมายเหตุใหม่และต่อท้ายลงในหน้า. subtype ยอมรับทั้งสตริงธรรมดา ("Text", "Square", "Highlight") หรือสมาชิก 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]},
)

การอ่านและอัปเดตคุณสมบัติ

get_property(name, default) อ่านค่าที่เฉพาะตามชนิดย่อย; set_property(name, value) เขียนค่า, และการตั้งค่าคุณสมบัติเป็น None จะลบออกจากพจนานุกรม properties ของหมายเหตุ.

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

ตั้งชื่อหมายเหตุด้วย AnnotationName

ชื่อ PDF (เช่น รายการ Name ของคำอธิบาย Stamp) ถูกทำเครื่องหมายแยกจากสตริงธรรมดาโดยใช้ AnnotationName, ซึ่งเป็นคลาสย่อย str จาก aspose_pdf.engine.cos. ค่าที่เก็บในลักษณะนี้ยังคงเทียบเท่ากับสตริงทั่วไป.

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")},
)

การแทรก, การลบ, และการล้างค่า

insert(index, subtype, rect, contents, title, appearance_normal, properties) วางคำอธิบายใหม่ที่ตำแหน่งเฉพาะ; delete(index) ลบคำอธิบายหนึ่งโดยใช้ดัชนี (ทำให้เกิด IndexError สำหรับดัชนีที่อยู่นอกช่วง); clear() ลบคำอธิบายทั้งหมดออกจากหน้า.

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

การสร้างลักษณะการแสดงผลของคำอธิบาย

Annotation.generate_appearance(force) สร้างสตรีมลักษณะการแสดงผล /AP /N สำหรับคำอธิบายหนึ่งรายการและคืนค่า True เมื่อมีเรนเดอร์สำหรับชนิดย่อยนั้น; AnnotationCollection.generate_appearances(force) ทำเช่นเดียวกันสำหรับคำอธิบายทั้งหมดบนหน้าด้วยการเรียกหนึ่งครั้งและคืนจำนวนคำอธิบายที่ถูกสร้างจริง (ชนิดย่อยที่ไม่รองรับจะถูกข้าม).

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

ชนิดย่อยของคำอธิบายและแฟล็ก

AnnotationType แสดงรายชื่อชื่อชนิดย่อยมาตรฐาน PDF 32000-1:2008 (ตาราง 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, และ REDACT.

AnnotationFlags คือ IntFlag ที่ครอบคลุมพฤติกรรมการแสดงผล/การโต้ตอบของคำอธิบาย: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED, และ TOGGLE_NO_VIEW.

รุ่นก่อนปล่อย: คำอธิบาย 3 มิติ

PDF3DAnnotation, PDF3DArtwork, PDF3DContent และ PDF3DView จำลองงานศิลปะ 3 มิติที่แนบอยู่กับหน้า — PDF3DAnnotation มี rect: Rectangle, artwork: PDF3DArtwork, และ background_color: Color ที่เป็นตัวเลือกเพิ่มเติม. PDF3DArtwork.add_view() ลงทะเบียน PDF3DView, แต่ละอันบรรจุ render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) และ lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM). คำอธิบายของไลบรารีเองระบุว่า PDF3DAnnotation เป็น “minimal annotation wrapper for prerelease imports” — ให้ถือว่าพื้นผิวนี้เป็นขั้นตอนเริ่มต้น ไม่ใช่ API 3D ที่พัฒนาสมบูรณ์.

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

• ควรใช้สมาชิก enum ของ AnnotationType แทนสตริง subtype ดิบเมื่อค่าต้องถูกเปรียบเทียบหรือใช้ในการแยกสาขาในส่วนอื่นของโค้ดของคุณ.
• เรียก set_property(name, None) เพื่อเอา property ออกโดยตรงแทนที่จะปล่อยให้ค่าที่ล้าสมัยค้างอยู่ — รายการจะหายไปจาก properties อย่างสมบูรณ์.
• สร้างลักษณะการแสดงผลเป็นชุดด้วย AnnotationCollection.generate_appearances แทนการวนลูป generate_appearance() ต่อ annotation; มันจะคืนค่าจำนวนที่สร้างจริงเพื่อให้คุณตรวจจับ subtype ที่ข้ามหรือไม่รองรับ.
• delete() และการทำดัชนีใน page.annotations ทั้งสองใช้ฐานศูนย์; ตรวจสอบดัชนีก่อนเรียก delete() หากมาจากการป้อนของผู้ใช้ เนื่องจากดัชนีที่อยู่นอกช่วงจะทำให้เกิด IndexError.
• ห่อค่าชื่อ PDF (เช่น Stamp’s Name) ด้วย AnnotationName เพื่อให้มันทำรอบเป็นชื่อ PDF แทนที่จะเป็นสตริงข้อความธรรมดา.

ปัญหาทั่วไป

FAQ

ฉันจะเพิ่มคำอธิบายความคิดเห็นแบบข้อความธรรมดาได้อย่างไร?

เรียก page.annotations.add("Text", (x0, y0, x1, y1), "comment text"). กลุ่มสี่ตัวเลขเป็นสี่เหลี่ยมของคำอธิบายบนหน้า.

ความแตกต่างระหว่าง Annotation, MarkupAnnotation และ LinkAnnotation คืออะไร?

Annotation คือมุมมองแบบเรียลไทม์ที่คืนค่ามาสำหรับคำอธิบายใด ๆ บนหน้า. MarkupAnnotation เป็นฐานสำหรับชนิดย่อยแบบ markup (ไฮไลท์, หมายเหตุข้อความ, รูปร่าง) และ LinkAnnotation ถูกเก็บไว้สำหรับคำอธิบายแบบลิงก์; ทั้งสองในขณะนี้เปิดเผยวิธี/คุณสมบัติเช่นเดียวกับ Annotation.

ฉันสามารถลบคุณสมบัติเดียวโดยไม่ลบคำอธิบายทั้งหมดได้หรือไม่?

ใช่ — เรียก annotation.set_property(name, None); คำอธิบายเองจะไม่ได้รับการแก้ไข, มีเพียงรายการนั้นเท่านั้นที่ถูกลบออกจาก properties.

AnnotationCollection.generate_appearances จะล้มเหลือหากซับไทป์ที่ไม่รองรับหรือไม่?

ไม่. มันข้ามซับไทป์ที่ไม่มีตัวเรนเดอร์ลักษณะในตัวและคืนค่าจำนวนของ annotation ที่มันได้สร้างลักษณะจริงๆ.

คลาส annotation 3D พร้อมสำหรับการใช้งานในสภาพการผลิตหรือไม่?

PDF3DAnnotation และประเภทที่เกี่ยวข้องได้รับการบันทึกเป็นตัวห่อหุ้มขั้นต่ำสำหรับการนำเข้าก่อนการปล่อย — ตรวจสอบพฤติกรรมกับโปรแกรมดู PDF ที่คุณมุ่งหมายก่อนพึ่งพาเพื่อเนื้อหา 3D ในการผลิต.

สรุป API Reference

ดูเพิ่มเติม

• Aspose.PDF for Python — Enterprise Documentation