داده‌های اولیه و متادیتای XMP

داده‌های اولیه و متادیتای XMP

Aspose.PDF FOSS برای Python ساختارهای سطح بالاتر API — Document، Page، و کلاس‌های حاشیه‌نویسی و فرم — را بر پایه مجموعه‌ای کوچک از انواع داده‌های اولیه تعریف‌شده در aspose_pdf.engine.data می‌سازد. به ندرت این موارد را به‌طور مستقیم می‌سازید، اما به‌طور مداوم به‌عنوان انواع ویژگی‌ها و مقادیر بازگشتی ظاهر می‌شوند: فرهنگ‌نامه منابع یک صفحه با مقادیر PdfName کلید می‌شود، رنگ‌ها نمونه‌های Color هستند، و Document.xmp_metadata یک XmpPacket بازمی‌گرداند. این راهنما primitives هویت شیء، wrapperهای مقدار اولیه، Color، enumهای رمزگذاری متن، و مدل متادیتای 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)

wrapperهای مقدار اولیه

PdfNumber و PdfName مقادیر خام PDF را در اشیاء Python تایپ‌شده می‌پیچند. PdfNumber مقدار عددی value خود را به‌عنوان یک Python بومی int یا float نگه می‌دارد؛ PdfName یک رشته name را نگه می‌دارد و نوعی است که برای کلیدهای فرهنگ‌نامه در سراسر مدل شیء سطح پایین استفاده می‌شود — برای مثال، کلیدهای Font و Resources در فرهنگ‌نامه منابع یک صفحه. PdfNull نمایانگر شیء null در 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 حل می‌کند. گترها و ستیرهای نوعی (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 ویژگی‌ای است که دارای مqualifierهای add_qualifier/remove_qualifier خود می‌باشد. هر چهار از یک بلوک ساختمانی XmpField یکسان برای مقادیر تک‌تک استفاده می‌کنند.

نکات و بهترین شیوه‌ها

• به جای ساخت از صفر، Document.xmp_metadata را بخوانید تا XmpPacket سند را به دست آورید — این مورد قبلاً از فایل بارگذاری‌شده پر شده است.
• به‌طور مستقیم PdfNumber.value را بخوانید — آن قبلاً شامل Python بومی int یا float است که به سازنده پاس داده‌اید؛ هیچ روش تبدیل to_double() یا to_int() وجود ندارد.
• به جای استفاده از تاپل‌های دست‌ساز r/g/b/a برای رنگ‌های رایج، از کارخانه‌های نام‌گذاری‌شده Color (Color.red()، Color.Black() و غیره) استفاده کنید — آن‌ها در نقاط فراخوانی واضح‌تر خوانده می‌شوند.
• 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