البدائيات البيانات وبيانات XMP الوصفية

بدائيات البيانات وبيانات XMP الوصفية

Aspose.PDF FOSS لـ Python يبني API ذات المستوى الأعلى — Document، Page، وفئات التعليقات والنماذج — على مجموعة صغيرة من الأنواع الأولية للبيانات المعرفة في aspose_pdf.engine.data. نادراً ما ستُنشئ معظم هذه مباشرةً، لكنها تظهر باستمرار كأنواع خصائص وقيم إرجاع: قاموس موارد الصفحة يُفهرس بواسطة قيم PdfName، الألوان هي مثيلات Color، و Document.xmp_metadata تُرجع XmpPacket. هذا الدليل يقدّم بدائيات هوية الكائن، أغلفة القيم الأولية، Color، تعدادات ترميز النص، ونموذج بيانات XMP الوصفي.

هوية الكائن وسجل الكائنات

PdfObjectID يحدد كائنًا غير مباشر في ملف PDF بواسطة object_number و generation_number. PdfObjectRegistry يعيّن ويتتبع هذه المعرفات أثناء تسلسل الكائنات، و PdfTrailerable هو العقد المشترك للكائنات التي يمكنها إنتاج القاموس المكتوب في ذيل PDF.

import aspose_pdf
from aspose_pdf.engine.data import PdfObjectRegistry

registry = PdfObjectRegistry()

# register() assigns a PdfObjectID to a serializable object
object_id = registry.register(some_pdf_object)
print(object_id.object_number, object_id.generation_number)

# get() resolves an object back from its PdfObjectID
resolved = registry.get(object_id)

أغلفة القيم الأولية

PdfNumber و PdfName يلتفان حول قيم PDF الخام في كائنات Python مُعرفة النوع. PdfNumber يحتفظ بـ value الرقمي كـ Python أصلي int أو float; PdfName يحتوي على سلسلة name وهو النوع المستخدم لمفاتيح القاموس عبر نموذج الكائنات منخفض المستوى — على سبيل المثال، مفاتيح Font و Resources في قاموس موارد الصفحة. PdfNull يمثل كائن PDF الفارغ.

import aspose_pdf
from aspose_pdf.engine.data.number import PdfNumber
from aspose_pdf.engine.data.types import PdfName

number = PdfNumber(3.14)
raw_value = number.value  # already the native int/float you passed in

resources_key = PdfName("Resources")
font_key = PdfName("Font")

قيم الألوان

يمثل Color لون RGBA مع خصائص عائمة r، g، b، وa. إلى جانب المُنشئ ذو الوسيطين زائد ألفا، يوفّر مجموعة كاملة من مُصنّعات الألوان المسماة — كلاً من الصيغة الصغيرة (aqua()، blue()، azure()، red()، green()، yellow()، black()، white()، gray()) و PascalCase من الأسماء المستعارة (Aqua()، Blue()، Azure()، Red()، Green()، Yellow()، Black()، White()، Gray()).

import aspose_pdf
from aspose_pdf.engine.data.types import Color

custom = Color(r=0.2, g=0.4, b=0.8, a=1.0)

# Named factories return ready-made Color instances
highlight = Color.yellow()
border = Color.Black()

ترميزات النص ومرشحات الدفق

EncodingType (WIN_ANSI، MAC_ROMAN، MAC_EXPERT، PDF_DOC، UNICODE) يحدد ترميز نص، وEncoding يوفّر ثوابت الترميز المطابقة (UTF8، UTF16، LATIN1، WIN_ANSI) إلى جانب طريقة encode(text, encoding_type) التي تُعيد الـbytes المشفر. FilterType (NONE، FLATE_DECODE، LZW_DECODE، DCT_DECODE، JPX_DECODE، CCITT_FAX_DECODE، JBIG2_DECODE) يحدد مرشح الدفق المطبق على محتوى PDF المضغوط.

import aspose_pdf
from aspose_pdf.engine.data import Encoding, EncodingType, FilterType

encoded = Encoding.encode("Hello, world", EncodingType.WIN_ANSI)

# FilterType values identify how a content or image stream is compressed
current_filter = FilterType.FLATE_DECODE

البيانات الوصفية XMP

XmpPacket هو النموذج الموجود في الذاكرة لحزمة البيانات الوصفية XMP الخاصة بالمستند — وهو النوع الذي تُعيده Document.xmp_metadata. يحتفظ بمجموعة مرتبة من fields (كل منها إما XmpField أو XmpArray أو XmpProperty) ويحلّ صيغ بادئات الفضاءات الاسمية عبر XmpNamespaceProvider. Typed getters and setters (get_value-style accessors مثل get_bool، get_int، get_real، get_date، get_localized_text، get_array، ونظيراتها من set_*) تقرأ وتكتب الخصائص الفردية بحسب بادئة الفضاء الاسمي أو URI واسم الخاصية.

import aspose_pdf

doc = aspose_pdf.Document()
doc.load_from("input.pdf")

xmp = doc.xmp_metadata  # XmpPacket

title = xmp.get_localized_text("dc", "title", lang="x-default")
xmp.set_value("dc", "creator", "Jane Doe")

serialized = xmp.serialize()

XmpStruct يُنمذج قيمة مُنظمة (rdf:parseType="Resource") مع بحث get(name) الخاص به، XmpArray يُنمذج مصفوفة مرتبة مع add(item) وremove(item)، وXmpProperty هو خاصية تحمل مؤهلات add_qualifier/remove_qualifier الخاصة بها. جميع الأربعة تشترك في نفس مكوّن XmpField للقيم الفردية.

نصائح وأفضل الممارسات

• اقرأ Document.xmp_metadata للحصول على XmpPacket للمستند بدلاً من بناء واحدة من الصفر — فهي مُعبأة بالفعل من الملف المحمّل.
• اقرأ PdfNumber.value مباشرة — فهو يحتوي بالفعل على Python int أو float الأصلي الذي مررته إلى المنشئ؛ لا توجد طريقة تحويل to_double() أو to_int().
• فضّل المصانع المُسماة Color (Color.red()، Color.Black()، إلخ) على tuples r/g/b/a المصنوعة يدوياً للألوان الشائعة — فهي تُقرأ بشكل أوضح في مواقع الاستدعاء.
• طابق EncodingType الذي تمرره إلى Encoding.encode() مع الترميز الذي يتوقعه الوجهة (الخط، الدفق، أو العارض) فعليًا؛ عدم تطابق ترميز نص PDF هو مصدر شائع للمخرجات المشوشة.
• عامل PdfObjectRegistry وPdfObjectID كأنهما أنواع منخفضة المستوى وموجهة للمحرك — معظم شفرة التطبيق تقرأ محتوى المستند عبر Document وPage بدلاً من تسجيل الكائنات مباشرةً.

مشكلات شائعة

FAQ

هل أحتاج إلى إنشاء PdfObjectID أو PdfObjectRegistry بنفسي؟

نادرًا. فهي تدعم عملية تسلسل المحرك؛ معظم شفرة التطبيق لا تُنشئها مباشرةً أبدًا إلا إذا كانت تعمل مع نموذج الكائنات منخفض المستوى.

ما هو الفرق بين XmpField، XmpArray، XmpStruct، و XmpProperty؟

XmpField هو قيمة عددية مفردة. XmpArray هي قائمة مرتبة من القيم، XmpStruct هي تجميع هيكلي (rdf:parseType="Resource") للحقول، وXmpProperty هي قيمة تحمل أيضًا مؤهلاتها الخاصة.

كيف أحصل على بيانات XMP الوصفية للوثيقة؟

اقرأ خاصية xmp_metadata على Document المحمّل — تُعيد XmpPacket يمكنك الاستعلام عنها وتحديثها في الموقع.

هل المصانع اللونية بالأحرف الصغيرة و PascalCase تمثل ألوانًا مختلفة؟

لا — Color.red() وColor.Red() هما أسماء مستعارة تُعيد نفس اللون؛ تم توفير كلا الشكلين للراحة.

API Reference ملخص

انظر أيضاً

• Aspose.PDF for Python — Enterprise Documentation