Datenprimitive und XMP-Metadaten

Datenprimitiven und XMP-Metadaten

Aspose.PDF FOSS für Python baut seine höherstufigen API — Document, Page und die Annotations- und Formularklassen — auf einem kleinen Satz primitiver Datentypen auf, die in aspose_pdf.engine.data definiert sind. Sie werden die meisten davon selten direkt konstruieren, aber sie tauchen ständig als Eigenschaftstypen und Rückgabewerte auf: Das Ressourcen-Dictionary einer Seite ist nach PdfName-Werten indiziert, Farben sind Color-Instanzen, und Document.xmp_metadata gibt ein XmpPacket zurück. Dieser Leitfaden stellt die Objekt-Identitäts-Primitiven, die Wrapper für primitive Werte, Color, die Enums für Textkodierung und das XMP-Metadaten-Modell vor.

Objektidentität und das Objektregister

PdfObjectID identifiziert ein indirektes Objekt in einer PDF-Datei anhand seiner object_number und generation_number. PdfObjectRegistry vergibt und verfolgt diese Kennungen, während Objekte serialisiert werden, und PdfTrailerable ist der gemeinsame Vertrag für Objekte, die das in einen PDF-Trailer geschriebenen Dictionary erzeugen können.

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 für primitive Werte

PdfNumber und PdfName verpacken rohe PDF-Werte in typisierte Python-Objekte. PdfNumber speichert seine numerische value als nativen Python int oder float; PdfName enthält einen name-String und ist der Typ, der für Dictionary-Schlüssel im gesamten Low-Level-Objektmodell verwendet wird — zum Beispiel die Font- und Resources-Schlüssel im Ressourcen-Dictionary einer Seite. PdfNull stellt das PDF-Null-Objekt dar.

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

Farbwerte

Color stellt eine RGBA-Farbe mit den Float-Eigenschaften r, g, b und a dar. Neben dem Konstruktor mit zwei Argumenten plus Alpha stellt es eine vollständige Menge benannter Farbfabriken bereit – sowohl in Kleinbuchstaben (aqua(), blue(), azure(), red(), green(), yellow(), black(), white(), gray()) als auch PascalCase Aliasse (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()

Textkodierungen und Stream-Filter

EncodingType (WIN_ANSI, MAC_ROMAN, MAC_EXPERT, PDF_DOC, UNICODE) identifiziert eine Textkodierung, und Encoding stellt die passenden Kodierungskonstanten bereit (UTF8, UTF16, LATIN1, WIN_ANSI) zusammen mit einer encode(text, encoding_type)-Methode, die das kodierte bytes zurückgibt. FilterType (NONE, FLATE_DECODE, LZW_DECODE, DCT_DECODE, JPX_DECODE, CCITT_FAX_DECODE, JBIG2_DECODE) identifiziert den angewendeten Stream-Filter für komprimierten PDF-Inhalt.

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

XmpPacket ist das In-Memory-Modell für das XMP-Metadaten-Paket eines Dokuments – es ist der von Document.xmp_metadata zurückgegebene Typ. Es hält eine geordnete Sammlung von fields (jeweils ein XmpField, XmpArray oder XmpProperty) und löst Namensraum-Präfixe über ein XmpNamespaceProvider auf. Typisierte Getter und Setter (get_value-Stil-Zugriffsmethoden wie get_bool, get_int, get_real, get_date, get_localized_text, get_array und deren set_*-Gegenstücke) lesen und schreiben einzelne Eigenschaften anhand von Namensraum-Präfix oder URI sowie Eigenschaftsname.

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 modelliert einen strukturierten (rdf:parseType="Resource") Wert mit seiner eigenen get(name)-Nachschlagefunktion, XmpArray modelliert ein geordnetes Array mit add(item) und remove(item), und XmpProperty ist eine Eigenschaft, die ihre eigenen add_qualifier/remove_qualifier-Qualifizierer trägt. Alle vier teilen denselben XmpField-Baustein für einzelne Werte.

Tipps und bewährte Verfahren

• Lese Document.xmp_metadata, um das XmpPacket des Dokuments zu erhalten, anstatt eines neuen von Grund auf zu erstellen – es ist bereits aus der geladenen Datei befüllt.
• Lese PdfNumber.value direkt — es enthält bereits das native Python int oder float, das Sie dem Konstruktor übergeben haben; es gibt keine to_double() oder to_int() Konvertierungsmethode.
• Bevorzuge die benannten Color-Fabriken (Color.red(), Color.Black() usw.) gegenüber selbstgeschriebenen r/g/b/a-Tupeln für gängige Farben — sie sind an Aufrufstellen lesbarer.
• Stimmen Sie das EncodingType, das Sie an Encoding.encode() übergeben, mit der Codierung ab, die das Ziel (Schriftart, Stream oder Viewer) tatsächlich erwartet; PDF-Textkodierungsinkonsistenzen sind eine häufige Ursache für fehlerhafte Ausgabe.
• Betrachten Sie PdfObjectRegistry und PdfObjectID als low-level, engine-seitige Typen — die meiste Anwendungscode liest Dokumenteninhalt über Document und Page, anstatt Objekte direkt zu registrieren.

Häufige Probleme

FAQ

Muss ich PdfObjectID oder PdfObjectRegistry selbst konstruieren?

Selten. Sie unterstützen den Serialisierungsprozess der Engine; die meiste Anwendungscode instanziiert sie nie direkt, es sei denn, er arbeitet mit dem low-level Objektmodell.

Was ist der Unterschied zwischen XmpField, XmpArray, XmpStruct und XmpProperty?

XmpField ist ein einzelner Skalarwert. XmpArray ist eine geordnete Liste von Werten, XmpStruct ist eine strukturierte (rdf:parseType="Resource") Gruppierung von Feldern, und XmpProperty ist ein Wert, der zudem eigene Qualifikatoren trägt.

Wie erhalte ich die XMP-Metadaten eines Dokuments?

Lese die xmp_metadata-Eigenschaft eines geladenen Document — sie gibt ein XmpPacket zurück, das Sie abfragen und direkt vor Ort aktualisieren können.

Sind die kleingeschriebene und PascalCase Color-Fabriken unterschiedliche Farben?

Nein — Color.red() und Color.Red() sind Aliase, die dieselbe Farbe zurückgeben; beide Schreibweisen werden aus Bequemlichkeitsgründen bereitgestellt.

API Reference Zusammenfassung

Siehe auch

• Aspose.PDF for Python — Enterprise Documentation