Datové primitivy a XMP metadata

Datové primitivy a XMP metadata

Aspose.PDF FOSS pro Python vytváří své vyšší úrovně API — Document, Page a třídy anotací a formulářů — na malé sadě primitivních datových typů definovaných v aspose_pdf.engine.data. Většinou tyto prvky přímo nekonstruktujete, ale neustále se objevují jako typy vlastností a návratové hodnoty: slovník zdrojů stránky je indexován hodnotami PdfName, barvy jsou instance Color a Document.xmp_metadata vrací XmpPacket. Tento průvodce představuje primitivy objektové identity, obalové typy primitivních hodnot, Color, výčty pro kódování textu a model Metadata XMP.

Identita objektu a registr objektů

PdfObjectID identifikuje nepřímý objekt v PDF souboru pomocí jeho object_number a generation_number. PdfObjectRegistry přiřazuje a sleduje tyto identifikátory během serializace objektů a PdfTrailerable je sdílená smlouva pro objekty, které mohou vytvořit slovník zapisovaný do PDF trailer.

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)

Obaly primitivních hodnot

PdfNumber a PdfName obalují surové PDF hodnoty do typovaných objektů Python. PdfNumber uchovává svou číselnou value jako nativní Python int nebo float; PdfName uchovává řetězec name a je typ používaný pro klíče slovníků v celém nízkoúrovňovém modelu objektů — například klíče Font a Resources ve slovníku zdrojů stránky. PdfNull představuje PDF nulový objekt.

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")

Hodnoty barev

Color představuje RGBA barvu s vlastnostmi typu float r, g, b a a. Kromě dvouargumentového konstruktoru s alfa kanálem poskytuje kompletní sadu pojmenovaných továrních metod pro barvy — jak malá písmena (aqua(), blue(), azure(), red(), green(), yellow(), black(), white(), gray()), tak PascalCase aliasy (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()

Kódování textu a filtry proudu

EncodingType (WIN_ANSI, MAC_ROMAN, MAC_EXPERT, PDF_DOC, UNICODE) identifikuje textové kódování a Encoding poskytuje odpovídající konstanty kódování (UTF8, UTF16, LATIN1, WIN_ANSI) spolu s metodou encode(text, encoding_type), která vrací zakódovaný bytes. FilterType (NONE, FLATE_DECODE, LZW_DECODE, DCT_DECODE, JPX_DECODE, CCITT_FAX_DECODE, JBIG2_DECODE) identifikuje proudový filtr použitý na komprimovaný obsah 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

Metadata XMP

XmpPacket je model v paměti pro XMP paket metadat dokumentu — jedná se o typ vrácený funkcí Document.xmp_metadata. Uchovává uspořádanou kolekci fields (každý je XmpField, XmpArray nebo XmpProperty) a rozpoznává prefixy jmenných prostorů pomocí XmpNamespaceProvider. Typované gettery a settery (get_value-stylové přístupové metody jako get_bool, get_int, get_real, get_date, get_localized_text, get_array a jejich set_* protějšky) čtou a zapisují jednotlivé vlastnosti podle prefixu jmenného prostoru nebo URI a názvu vlastnosti.

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 modeluje strukturovanou (rdf:parseType="Resource") hodnotu se svým vlastním vyhledáváním get(name), XmpArray modeluje uspořádané pole s add(item) a remove(item), a XmpProperty je vlastnost, která nese své vlastní kvalifikátory add_qualifier/remove_qualifier. Všechny čtyři sdílejí stejný stavební blok XmpField pro jednotlivé hodnoty.

Tipy a osvědčené postupy

• Přečtěte Document.xmp_metadata, abyste získali XmpPacket dokumentu, místo abyste jej vytvářeli od nuly — je již naplněno z načteného souboru.
• Přečtěte PdfNumber.value přímo — již obsahuje nativní Python int nebo float, které jste předali konstruktoru; neexistuje žádná metoda převodu to_double() nebo to_int().
• Upřednostňujte pojmenované továrny Color (Color.red(), Color.Black() a další) před ručně vytvořenými n-ticemi r/g/b/a pro běžné barvy — čtou se na místech volání přehledněji.
• Přizpůsobte EncodingType, který předáváte do Encoding.encode(), kódování, které cílové místo (písmo, proud nebo prohlížeč) skutečně očekává; nesoulad kódování textu v PDF je častým zdrojem zkresleného výstupu.
• Považujte PdfObjectRegistry a PdfObjectID za nízkoúrovňové typy orientované na engine — většina aplikačního kódu čte obsah dokumentu přes Document a Page místo přímé registrace objektů.

Časté problémy

FAQ

Musím sám vytvářet PdfObjectID nebo PdfObjectRegistry?

Zřídka. Podporují proces serializace enginu; většina aplikačního kódu je nikdy neinstancuje přímo, pokud nepracuje s nízkoúrovňovým modelem objektů.

Jaký je rozdíl mezi XmpField, XmpArray, XmpStruct a XmpProperty?

XmpField je jednorozměrná skalární hodnota. XmpArray je uspořádaný seznam hodnot, XmpStruct je strukturované (rdf:parseType="Resource") seskupení polí a XmpProperty je hodnota, která také nese své vlastní kvalifikátory.

Jak získám XMP metadata dokumentu?

Přečtěte vlastnost xmp_metadata na načteném Document — vrátí XmpPacket, který můžete dotazovat a aktualizovat přímo.

Jsou malá a PascalCase Color factory jiné barvy?

Ne — Color.red() a Color.Red() jsou aliasy, které vrací stejnou barvu; obě zápisy jsou poskytovány pro pohodlí.

API Reference Shrnutí

Viz také:

• Aspose.PDF for Python — Enterprise Documentation