إدارة المستندات في Python: النماذج، الخطوط، والمرفقات

مقدمة

Aspose.PDF FOSS لـ Python يركز على الفئة Document، التي تُظهر pages، form، outlines، tagged_content، وattachments كنقاط دخول للتحرير الهيكلي وعلى مستوى المستند. بخلاف إضافة محتوى الصفحة، تغطي المكتبة العمليات التي تجعل ملف PDF كيانًا كاملاً يمكن توزيعه: حقول نماذج تفاعلية تجمع وتعرض بيانات منظمة، مرفقات ملفات على مستوى المستند، اكتشاف الخطوط وتضمينها لتأليف النص، وشجرة إشارات مرجعية للتنقل. كل واحدة من هذه المجالات تُطلق أخطاءً عبر تسلسل استثناءات واحد جذره AsposePdfException، بحيث يمكن للمتصلين التقاط فشل الحزمة المحدد دون التخمين بشأن أنواع الاستثناءات وحدةً بوحدة.

يوضح هذا الدليل كيفية العمل مع تلك الواجهة لإدارة المستندات: التقاط وتمييز الفئات الفرعية لـ 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. معظم فشل عمليات معالجة المستندات يقع تحت الفئة الفرعية PdfException، والتي بدورها هي الأساس لـ PdfParseException (إدخال غير صالح)، PdfSecurityException (أخطاء التشفير وكلمات المرور، بما فيها InvalidPasswordException)، وPdfValidationException (فشل هيكلي أو امتثال). التقاط AsposePdfException في النهاية، بعد الفئات الفرعية الأكثر تحديدًا، يتيح للمتصل أن يتفاعل بشكل مختلف مع كلمة مرور خاطئة مقارنةً بملف تالف مع الحفاظ على وجود احتياطي واحد لكل ما يمكن أن تطرحه الحزمة.

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 يُرجِع واجهة 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 في PDF عند الحفظ، مع نوع MIME اختياري، وصف، وتواريخ الإنشاء/التعديل. 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() يحلان الخط حسب العائلة، الاسم الكامل، أو اسم 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")

البدء السريع

ثبت الحزمة، ثم أنشئ مستندًا يجمع بين إشارة مرجعية، وبيانات تعريف المستند، ومرفق في برنامج نصي واحد.

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.

البدء

• البدء
• دليل المطور
• مقالات قاعدة المعرفة
• API Reference
• GitHub المستودع

الموارد ذات الصلة

• Aspose.PDF — Enterprise Blog