פרימיטיבים של נתונים ו-Metadata של 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 הוא החוזה המשותף לאובייקטים שיכולים ליצור את המילון שנכתב בתור trailer של 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 מייצג את אובייקט ה-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-סגנון, כגון 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(), וכדומה) על פני טאפלים 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