Gegevensprimitieven en XMP-metadata

Gegevensprimitieven en XMP-metadata

Aspose.PDF FOSS voor Python bouwt zijn hoger-niveau API — Document, Page, en de annotatie- en formuliervelden — bovenop een kleine set primitieve gegevenstypen gedefinieerd in aspose_pdf.engine.data. Je zult de meeste hiervan zelden direct construeren, maar ze komen voortdurend voor als eigenschapstypen en retourwaarden: het resource-woordenboek van een pagina wordt geïndexeerd met PdfName-waarden, kleuren zijn Color-instanties, en Document.xmp_metadata retourneert een XmpPacket. Deze gids introduceert de object-identiteitsprimitieven, de primitieve-waardeverpakkingen, Color, de tekst-codering-enums en het XMP-metadata-model.

Objectidentiteit en het objectregister

PdfObjectID identificeert een indirect object in een PDF-bestand aan de hand van zijn object_number en generation_number. PdfObjectRegistry kent deze identifiers toe en houdt ze bij terwijl objecten worden geserializeerd, en PdfTrailerable is het gedeelde contract voor objecten die het woordenboek kunnen produceren dat in een PDF-trailer wordt geschreven.

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)

Primitieve waardeverpakkingen

PdfNumber en PdfName verpakken ruwe PDF-waarden in getypeerde Python-objecten. PdfNumber bewaart zijn numerieke value als een native Python int of float; PdfName bevat een name-string en is het type dat wordt gebruikt voor woordenboek-sleutels door het hele low-level objectmodel — bijvoorbeeld de Font en Resources-sleutels in het resource-woordenboek van een pagina. PdfNull vertegenwoordigt het PDF-null-object.

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

Kleurwaarden

Color vertegenwoordigt een RGBA-kleur met r, g, b en a float-eigenschappen. Naast de twee-argument-plus-alpha-constructor biedt het een volledige reeks benoemde kleur-fabrieken — zowel kleine letters (aqua(), blue(), azure(), red(), green(), yellow(), black(), white(), gray()) en PascalCase aliassen (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()

Tekstcoderingen en streamfilters

EncodingType (WIN_ANSI, MAC_ROMAN, MAC_EXPERT, PDF_DOC, UNICODE) identificeert een tekstcodering, en Encoding biedt de bijbehorende coderingsconstanten (UTF8, UTF16, LATIN1, WIN_ANSI) naast een encode(text, encoding_type)-methode die de gecodeerde bytes retourneert. FilterType (NONE, FLATE_DECODE, LZW_DECODE, DCT_DECODE, JPX_DECODE, CCITT_FAX_DECODE, JBIG2_DECODE) identificeert het streamfilter dat wordt toegepast op gecomprimeerde PDF-inhoud.

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-metadata

XmpPacket is het in-memory model voor een document-XMP-metadata-pakket — het is het type dat wordt geretourneerd door Document.xmp_metadata. Het bevat een geordende verzameling van fields (elk een XmpField, XmpArray of XmpProperty) en lost namespace-prefixes op via een XmpNamespaceProvider. Getypeerde getters en setters (get_value-stijl accessors zoals get_bool, get_int, get_real, get_date, get_localized_text, get_array, en hun set_* tegenhangers) lezen en schrijven individuele eigenschappen op basis van namespace-prefix of URI en eigenschapsnaam.

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 modelleert een gestructureerde (rdf:parseType="Resource") waarde met zijn eigen get(name) lookup, XmpArray modelleert een geordende array met add(item) en remove(item), en XmpProperty is een eigenschap die zijn eigen add_qualifier/remove_qualifier qualifiers draagt. Alle vier delen hetzelfde XmpField bouwblok voor individuele waarden.

Tips en Best Practices

• Lees Document.xmp_metadata om de XmpPacket van het document te verkrijgen in plaats van er één vanaf nul te bouwen — deze is al gevuld vanuit het geladen bestand.
• Lees PdfNumber.value rechtstreeks — het bevat al de native Python int of float die je aan de constructor hebt doorgegeven; er is geen to_double() of to_int() conversiemethode.
• Geef de benoemde Color factories (Color.red(), Color.Black(), enzovoort) de voorkeur boven handmatig samengestelde r/g/b/a tuples voor algemene kleuren — ze zijn duidelijker leesbaar op aanroepplaatsen.
• Stem de EncodingType die je doorgeeft aan Encoding.encode() af op de codering die de bestemming (lettertype, stream of viewer) werkelijk verwacht; PDF-tekstcodering mismatches zijn een veelvoorkomende oorzaak van verwarde output.
• Beschouw PdfObjectRegistry en PdfObjectID als low-level, engine-gerichte types — de meeste toepassingscode leest documentinhoud via Document en Page in plaats van objecten direct te registreren.

Veelvoorkomende problemen

FAQ

Moet ik PdfObjectID of PdfObjectRegistry zelf aanmaken?

Zelden. Ze ondersteunen het serialisatieproces van de engine; de meeste toepassingscode instantiateert ze nooit rechtstreeks, tenzij ze met het low-level objectmodel werken.

Wat is het verschil tussen XmpField, XmpArray, XmpStruct en XmpProperty?

XmpField is een enkele scalare waarde. XmpArray is een geordende lijst van waarden, XmpStruct is een gestructureerde (rdf:parseType="Resource") groepering van velden, en XmpProperty is een waarde die ook zijn eigen kwalificaties draagt.

Hoe haal ik de XMP-metadata van een document op?

Lees de xmp_metadata eigenschap op een geladen Document — het retourneert een XmpPacket die je kunt opvragen en ter plaatse kunt bijwerken.

Zijn de kleine letters en de PascalCase Color-factories verschillende kleuren?

Nee — Color.red() en Color.Red() zijn aliassen die dezelfde kleur retourneren; beide spellingen worden ter gemak aangeboden.

API Reference Samenvatting

Zie ook

• Aspose.PDF for Python — Enterprise Documentation