Примітиви даних та XMP-метадані

Примітиви даних та XMP-метадані

Aspose.PDF FOSS for 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-null об’єкт.

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 float-властивостями. Окрім конструктора з двома аргументами плюс альфа, він надає повний набір іменованих фабрик кольорів — як у нижньому регістрі (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. Типізовані getter-и та setter-и (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 factories різними кольорами?

Ні — Color.red() і Color.Red() — це синоніми, які повертають один і той самий колір; обидва написання надаються для зручності.

API Reference Огляд

Дивіться також

• Aspose.PDF for Python — Enterprise Documentation