วิธีทำงานกับหมายเหตุ PDF ใน Python

Aspose.PDF FOSS for Python เปิดเผยทุกคำอธิบายบนหน้าเป็นวัตถุ Annotation ที่สดผ่าน AnnotationCollection ของหน้า, ดังนั้นคุณสามารถเพิ่มการทำเครื่องหมาย, ลิงก์, และคำอธิบาย 3D, ตรวจสอบคุณสมบัติเฉพาะประเภทของมัน, และสร้างสตรีมการแสดงผลที่โปรแกรมอ่าน PDF ต้องการเพื่อเรนเดอร์ — ทั้งหมดจาก Python แท้ๆ. คู่มือนี้แสดงวิธีการติดตั้งไลบรารี, เพิ่มคำอธิบาย, อ่านกลับ, และสร้างสตรีมการแสดงผลของมัน.

คู่มือแบบทีละขั้นตอน

git clone https://github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python.git
cd Aspose-PDF-FOSS-for-Python
pip install -e .

import aspose_pdf
print("aspose_pdf OK")

from aspose_pdf import Document
from aspose_pdf.annotations import (
    Annotation,
    AnnotationType,
    AnnotationFlags,
    MarkupAnnotation,
    LinkAnnotation,
)

from aspose_pdf import Document

document = Document()
document.pages.add()
page = document.pages[0]

annotation = page.annotations.add(
    "Highlight",
    (100, 700, 300, 720),
    "Key clause",
)
print(type(annotation).__name__)   # MarkupAnnotation
print(annotation.contents)         # Key clause

from aspose_pdf import Document
from aspose_pdf.annotations import AnnotationType

document = Document()
document.pages.add()
page = document.pages[0]

annotation = page.annotations.add(
    AnnotationType.POLYGON,
    (0, 0, 10, 10),
    "",
    properties={"Vertices": [0, 0, 10, 0, 5, 10]},
)
print(annotation.subtype)                    # Polygon
print(annotation.get_property("Vertices"))   # [0, 0, 10, 0, 5, 10]

from aspose_pdf import Document

document = Document()
document.pages.add()
page = document.pages[0]
page.annotations.add("Text", (50, 50, 70, 70), "First note")
page.annotations.add("Text", (80, 80, 100, 100), "Second note")

for annotation in page.annotations:
    print(annotation.subtype, "-", annotation.contents)

from aspose_pdf import Document
from aspose_pdf.engine.cos import AnnotationName

document = Document()
document.pages.add()
page = document.pages[0]

stamp = page.annotations.add(
    "Stamp",
    (100, 100, 260, 150),
    "",
    properties={"Name": AnnotationName("Approved")},
)
if stamp.generate_appearance():
    print(f"Appearance stream: {len(stamp.appearance_normal)} byte(s)")

# Regenerate every missing appearance stream on the page in one call:
count = page.annotations.generate_appearances(force=True)
print(f"Regenerated {count} appearance stream(s)")

from aspose_pdf import Document
from aspose_pdf.annotations import LinkAnnotation, MarkupAnnotation

document = Document()
document.pages.add()
page = document.pages[0]

link = page.annotations.add("Link", (50, 750, 200, 770), "")
highlight = page.annotations.add("Highlight", (50, 700, 200, 720), "")

print(isinstance(link, LinkAnnotation))         # True
print(isinstance(highlight, MarkupAnnotation))  # True

ปัญหาที่พบบ่อยและวิธีแก้

get_property returns None สำหรับคุณสมบัติที่ฉันเพิ่งตั้งค่า

properties คีย์ต้องตรงกันและคำนึงถึงตัวพิมพ์ใหญ่/เล็กของชื่อฟิลด์ PDF ("Vertices", "Name" และอื่น ๆ) — การพิมพ์ผิดหรือกรณีตัวอักษรที่ไม่ถูกต้องจะถูกละเว้นอย่างเงียบโดยไม่แจ้งข้อผิดพลาด ส่งอาร์กิวเมนต์ default ไปยัง get_property(name, default) และตรวจสอบอย่างชัดเจนขณะดีบัก subtype ใหม่.

generate_appearance() returns False

ไม่ใช่ทุกการจับคู่ของประเภทย่อยและคุณสมบัติที่สามารถสังเคราะห์เป็นสตรีมลักษณะโดยตัวสร้างในตัวได้ ตรวจสอบ has_appearance ก่อนสมมติว่าการเรียกสำเร็จ และจัดหา appearance_normal ที่เรนเดอร์ล่วงหน้า (bytes) โดยตรงบน add() สำหรับประเภทย่อยที่ตัวสร้างไม่ครอบคลุม.

คลาสย่อยของ annotation ที่ไม่คาดคิดหลังจาก add()

สตริงประเภทย่อย (หรือสมาชิก AnnotationType) ที่คุณส่งจะกำหนดคลาสที่คืนค่า: ประเภทย่อยของ markup จะกลับมาเป็น MarkupAnnotation, "Link" จะกลับมาเป็น LinkAnnotation, และประเภทย่อยที่รู้จักอื่นใดจะกลับมาเป็น Annotation พื้นฐาน ใช้ isinstance() กับ MarkupAnnotation/LinkAnnotation แทนการสมมติสตริงประเภทย่อยเฉพาะ.

AnnotationFlags ค่าดูเหมือนไม่เปลี่ยนการเรนเดอร์

AnnotationFlags (PRINT, HIDDEN, NO_ZOOM, READ_ONLY และที่คล้ายกัน) เป็น enum มาตรฐานของ Python IntFlag สำหรับการประกอบและตีความบิตพฤติกรรมของคำอธิบายด้วยตัวดำเนินการ | — เป็นประเภทค่า ไม่ใช่คุณสมบัติที่ Annotation.add() เขียนอัตโนมัติ ผสานรวมธงที่คุณต้องการและส่งผ่านกลไก properties เฉพาะประเภทเดียวกันที่ใช้สำหรับข้อมูลเฉพาะประเภทย่อยอื่น ๆ.

ทำงานกับหน้า ที่ยังไม่มีคำอธิบายใด ๆ

page.annotations จะเป็น AnnotationCollection ที่ถูกต้องเสมอ (อาจว่างเปล่า) — คุณไม่จำเป็นต้องตรวจสอบ None ก่อนเรียก add(), ทำการวนลูป, หรือเรียก clear().

คำถามที่พบบ่อย

ประเภทย่อยของ annotation ใดที่ Aspose.PDF FOSS สำหรับ Python รองรับ?

AnnotationType แสดงรายการประเภทย่อยมาตรฐาน PDF 32000-1:2008 Table 169 ทั้งหมด 25 ประเภท รวมถึง TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, HIGHLIGHT, STAMP, INK, FILE_ATTACHMENT, REDACT และอื่น ๆ.

ไลบรารีนี้รองรับ annotation 3D หรือไม่?

ใช่. PDF3DAnnotation, พร้อมกับ PDF3DArtwork, PDF3DContent, PDF3DView, PDF3DLightingScheme, และ PDF3DRenderMode, สร้างโมเดลพื้นผิว annotation PDF 3D ขั้นพื้นฐาน (สี่เหลี่ยม, งานศิลปะฝังตัว, และมุมมองที่ตั้งชื่อ) สำหรับเวิร์กโฟลว์ PDF 3D ก่อนปล่อย. ดูที่ อ้างอิง PDF3DAnnotation สำหรับชุดคุณสมบัติทั้งหมดของมัน.

ฉันจะลบ annotation จากหน้าอย่างไร?

เรียก page.annotations.delete(index) เพื่อลบ annotation หนึ่งรายการตามตำแหน่ง หรือ page.annotations.clear() เพื่อลบ annotation ทั้งหมดบนหน้า.

ฉันสามารถแทรก annotation ในตำแหน่งเฉพาะแทนการต่อท้ายได้หรือไม่?

ใช่ — AnnotationCollection.insert(index, subtype, rect, contents, title, appearance_normal, properties) รับอาร์กิวเมนต์เดียวกันกับ add() พร้อมกับเป้าหมาย index.

สีของ annotation แสดงอย่างไร?

คุณสมบัติ color บน Annotation (และคลาสย่อยของมัน) เป็น tuple[float, ...] ที่ตรงกับจำนวนส่วนประกอบของรายการ PDF /C (ว่างเมื่อสีไม่ได้ตั้งค่า) — ไม่ใช่วัตถุสีเฉพาะ.

ดูเพิ่มเติม

• การจัดการเอกสาร (คู่มือผู้พัฒนา)
• วิธีโหลดเอกสารใน Python
• คู่มือการติดตั้ง
• API Reference
• คลัง GitHub
• Aspose.PDF for Python — Enterprise Knowledge Base