การจัดการเอกสารใน Python: แบบฟอร์ม, ฟอนต์, และไฟล์แนบ

บทนำ

Aspose.PDF FOSS สำหรับ Python มุ่งเน้นที่คลาส Document, ซึ่งเปิดให้เข้าถึง pages, form, outlines, tagged_content, และ attachments เป็นจุดเริ่มต้นสำหรับการแก้ไขเชิงโครงสร้างและระดับเอกสาร นอกจากการเพิ่มเนื้อหาในหน้าแล้ว ไลบรารียังครอบคลุมการดำเนินการที่ทำให้ PDF เป็นศิลปวัตถุที่สมบูรณ์และสามารถแจกจ่ายได้: ฟิลด์ฟอร์มเชิงโต้ตอบที่รวบรวมและเปิดเผยข้อมูลเชิงโครงสร้าง, ไฟล์แนบระดับเอกสาร, การค้นหาและฝังฟอนต์สำหรับการเขียนข้อความ, และต้นไม้บุ๊กมาร์กสำหรับการนำทาง ทุกส่วนเหล่านี้จะโยงข้อผิดพลาดผ่านลำดับชั้นของ exception เดียวที่เริ่มต้นจาก AsposePdfException, เพื่อให้ผู้เรียกสามารถจับข้อผิดพลาดเฉพาะแพ็กเกจได้โดยไม่ต้องคาดเดาประเภทของ exception ทีละโมดูล.

คู่มือนี้แสดงวิธีการทำงานกับพื้นผิวการจัดการเอกสารนั้น: การจับและแยกแยะ subclass ของ AsposePdfException, การสร้างและอ่านฟิลด์ AcroForm ด้วย Form และ Field, การฝังและกู้คืนไฟล์แนบผ่าน FileSpecification, การแก้ไขฟอนต์ด้วย FontRepository และ FontRegistry, และการสร้างต้นไม้บุ๊กมาร์กด้วย OutlineCollection และ OutlineItem. แต่ละส่วนใช้เฉพาะคลาสและเมธอดที่มีอยู่ในแพ็กเกจปัจจุบัน.

Aspose.PDF FOSS สำหรับ Python เป็นแพ็กเกจ Python, aspose-pdf-foss-for-python, เผยแพร่ภายใต้สัญญาอนุญาต MIT, ต้องการ Python 3.11 หรือสูงกว่า ชื่อโมดูลระดับบนสุดคือ aspose_pdf. แพ็กเกจหลักขึ้นอยู่เฉพาะกับ cryptography และ asn1crypto; ส่วนเสริมเพิ่มเติมจะเพิ่มการถอดรหัสภาพโดยใช้ Pillow, การสนับสนุนฟอนต์ WOFF2 โดย Brotli, และการจัดวางข้อความซับซ้อนที่อิง HarfBuzz.

คุณลักษณะสำคัญ

การจัดการข้อยกเว้นด้วย AsposePdfException

ข้อผิดพลาดที่เฉพาะเจาะจงต่อแพ็กเกจใน Aspose.PDF FOSS สำหรับ Python ทั้งหมดสืบทอดจาก AsposePdfException. ความล้มเหลวส่วนใหญ่ในการประมวลผลเอกสารอยู่ภายใต้ subclass PdfException ของมัน, ซึ่งต่อมามีฐานสำหรับ PdfParseException (ข้อมูลที่ผิดรูปแบบ), PdfSecurityException (ข้อผิดพลาดการเข้ารหัสและรหัสผ่าน, รวมถึง InvalidPasswordException), และ PdfValidationException (ข้อผิดพลาดเชิงโครงสร้างหรือการปฏิบัติตาม). การจับ AsposePdfException สุดท้าย, หลังจาก subclass ที่เจาะจงมากกว่า, ทำให้ผู้เรียกสามารถตอบสนองแตกต่างกันระหว่างรหัสผ่านไม่ถูกต้องกับไฟล์ที่เสียหาย ในขณะที่ยังคงมีวิธีสำรองเดียวสำหรับข้อผิดพลาดอื่น ๆ ที่แพ็กเกจอาจโยงขึ้น.

from aspose_pdf import Document
from aspose_pdf.exceptions import (
    AsposePdfException,
    InvalidPasswordException,
    PdfParseException,
)


def open_document(path, password=None):
    try:
        document = Document()
        document.load_from(path, password=password)
        return document
    except InvalidPasswordException:
        print(f"{path}: a correct password is required")
    except PdfParseException as error:
        print(f"{path}: not a valid PDF ({error})")
    except AsposePdfException as error:
        # Catches every other aspose_pdf-specific error not handled above.
        print(f"{path}: PDF operation failed ({error})")
    return None

ฟิลด์แบบฟอร์มแบบโต้ตอบ

Document.form ส่งคืน façade Form บนฟิลด์ AcroForm ของเอกสาร. Form.add_text_field(), add_checkbox(), และ add_radio_group() สร้างฟิลด์เทอร์มินัลใหม่ที่เชื่อมกับหน้าและสี่เหลี่ยมวิดเจ็ต, แต่ละอันส่งคืน Field. Field เปิดเผย name, value, และ field_type เพื่อให้สามารถตรวจสอบและอัปเดตฟิลด์ที่มีอยู่ตามชื่อ, และ Field.remove() ลบฟิลด์ออกอย่างสมบูรณ์.

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()

    document.form.add_text_field("customer_name", page, (72, 700, 300, 720))
    document.form.add_checkbox("subscribe", page, (72, 670, 90, 688), on_value="Yes")
    document.form.add_radio_group(
        "plan",
        page,
        {"Basic": (72, 630, 90, 648), "Pro": (72, 600, 90, 618)},
        value="Basic",
    )

    for field in document.form.fields:
        print(field.name, field.field_type, field.value)

    for field in document.form.fields:
        if field.name == "customer_name":
            field.value = "Jane Doe"

    document.form.generate_appearances()
    document.save("form.pdf")

ไฟล์ฝังและเอกสารแนบ

Document.add_attachment ฝังไบต์เป็นไฟล์แนบระดับเอกสาร, เขียนลงใน /Names /EmbeddedFiles name tree ของ PDF เมื่อบันทึก, พร้อมกับ MIME type, คำอธิบาย, และวันที่สร้าง/แก้ไขตามต้องการ. Document.embedded_files อ่านทุกไฟล์แนบกลับเป็น FileSpecification ที่มีประเภท (name, contents, mime_type, description, size), และ Document.get_embedded_file ค้นหาไฟล์แนบตามชื่อ. FileSpecification.save() เขียนไบต์ที่กู้คืนลงดิสก์.

from aspose_pdf import Document

with Document() as document:
    document.pages.add()
    document.add_attachment(
        "notes.txt",
        b"Reviewed and approved.",
        mime="text/plain",
        description="Reviewer notes",
    )
    document.save("with-attachment.pdf")

with Document() as document:
    document.load_from("with-attachment.pdf")

    for spec in document.embedded_files:
        print(spec.name, spec.mime_type, spec.size)

    notes = document.get_embedded_file("notes.txt")
    if notes is not None:
        notes.save("notes-recovered.txt")

การค้นหาและฝังฟอนต์

FontRepository รวมแหล่งฟอนต์และแก้ไขฟอนต์ตามชื่อทั่วทั้งเอกสาร. FontRepository.add_source() ลงทะเบียน FontSource เช่น FolderFontSource (สแกนไดเรกทอรี, สามารถทำแบบเรียกซ้ำได้); FontRepository.find_font() และ search() จากนั้นแก้ไขฟอนต์ตาม family, full, หรือชื่อ PostScript, แล้วถอยกลับไปที่รีจิสทรีฟอนต์มาตรฐาน. การจับคู่อย่างแต่ละเป็น FontDescriptor, ซึ่งสามารถส่งต่อโดยตรงไปยัง Page.add_text เพื่อฝังและตัดส่วนของฟอนต์. FontRegistry ทำแผนที่ชื่อที่ไม่เป็นมาตรฐานทั่วไป (Arial, Times New Roman, และที่คล้ายกัน) ไปยัง Standard-14 ที่ใกล้ที่สุดผ่าน search_font_by_name().

from aspose_pdf import Document, FolderFontSource, FontRepository
from aspose_pdf.font_registry import FontRegistry

FontRepository.add_source(FolderFontSource("./fonts", scan_subdirectories=True))

descriptor = FontRepository.find_font("Open Sans")
if descriptor is None:
    # Fall back to the closest Standard-14 match for a common font name.
    descriptor = FontRegistry().search_font_by_name("Arial")

with Document() as document:
    page = document.pages.add()
    page.add_text(
        "Rendered with a resolved font",
        x=72,
        y=700,
        font_size=14,
        font=descriptor,
    )
    document.save("font-sample.pdf")

โครงร่างเอกสารและบุ๊กมาร์ก

Document.outlines ส่งคืน OutlineCollection, ตัวคอนเทนเนอร์ระดับบนสุดสำหรับต้นไม้บุ๊กมาร์กของ PDF. OutlineCollection.add เพิ่ม OutlineItem ระดับบนสุด; OutlineItem.add() ใส่บุ๊กมาร์กลูกภายใต้บุ๊กมาร์กที่มีอยู่. แต่ละ OutlineItem มี title, page_index เป้าหมาย, และแฟล็กการแสดงผล is_bold / is_italic, และเปิดเผยรายการ children ของตนเอง.

from aspose_pdf import Document
from aspose_pdf.outlines import OutlineItem

with Document() as document:
    document.pages.add()
    document.pages.add()

    chapter = OutlineItem("Chapter 1: Overview", page_index=0)
    document.outlines.add(chapter)
    chapter.add(OutlineItem("Section 1.1", page_index=0, is_italic=True))
    document.outlines.add(OutlineItem("Chapter 2: Details", page_index=1, is_bold=True))

    document.save("bookmarked.pdf")

เริ่มต้นอย่างรวดเร็ว

ติดตั้งแพ็กเกจแล้วสร้างเอกสารที่รวมบุ๊กมาร์ก, เมตาดาต้าเอกสาร, และไฟล์แนบในสคริปต์เดียว.

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

from aspose_pdf import Document
from aspose_pdf.outlines import OutlineItem

with Document() as document:
    page = document.pages.add()
    page.add_text("Quarterly Report", x=72, y=740, font_size=20)

    document.outlines.add(OutlineItem("Quarterly Report", page_index=0))
    document.info = {"Title": "Quarterly Report"}
    document.add_attachment(
        "source-data.csv", b"quarter,total\nQ1,1000\n", mime="text/csv"
    )
    document.save("report.pdf")

with Document() as reopened:
    reopened.load_from("report.pdf")
    print(reopened.page_count, "page(s),", reopened.info.get("Title"))
    print([spec.name for spec in reopened.embedded_files])

รูปแบบที่รองรับ

Page.render, Page.save_as_image, และ Document.save_page_as_image ยังผลิตผลลัพธ์ราสเตอร์ PNG ควบคู่กับ TIFF.

เหล่านี้เป็นผลลัพธ์การเรสเตอร์หน้าแทนที่จะเป็นรูปแบบการโหลดเอกสาร.

โอเพ่นซอร์สและลิขสิทธิ์

Aspose.PDF FOSS สำหรับ Python ถูกปล่อยภายใต้ใบอนุญาต MIT: ไม่มีข้อจำกัดการใช้งาน, ไม่มีค่าธรรมเนียมการรันไทม์, และไม่มีข้อกำหนดการลงทะเบียนสำหรับการใช้เชิงพาณิชย์หรือส่วนบุคคล. โค้ดต้นฉบับถูกโฮสต์ที่ github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, และแพ็กเกจถูกเผยแพร่บน PyPI ในชื่อ aspose-pdf-foss-for-python.

เริ่มต้นใช้งาน

• เริ่มต้นใช้งาน
• คู่มือผู้พัฒนา
• บทความ KB
• API Reference
• GitHub คลัง

แหล่งข้อมูลที่เกี่ยวข้อง

• Aspose.PDF — Enterprise Blog