Primitive de date și metadate XMP

Primitive de date și metadate XMP

Aspose.PDF FOSS pentru Python își construiește nivelul superior API — Document, Page, și clasele de adnotare și formular — pe baza unui set mic de tipuri de date primitive definite în aspose_pdf.engine.data. Vei construi rar majoritatea acestor elemente direct, dar ele apar constant ca tipuri de proprietăți și valori de returnare: dicționarul de resurse al unei pagini este indexat de valori PdfName, culorile sunt instanțe Color, iar Document.xmp_metadata returnează un XmpPacket. Acest ghid introduce primitivele de identitate a obiectelor, wrapper-ele de valori primitive, Color, enum-urile de codare a textului și modelul de metadate XMP.

Identitatea obiectului și registrul de obiecte

PdfObjectID identifică un obiect indirect într-un fișier PDF prin object_number și generation_number. PdfObjectRegistry atribuie și urmărește acești identificatori pe măsură ce obiectele sunt serializate, iar PdfTrailerable este contractul comun pentru obiectele care pot produce dicționarul scris în trailer-ul 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)

Wrapper-e de valori primitive

PdfNumber și PdfName împachetează valorile PDF brute în obiecte Python tipizate. PdfNumber păstrează value numeric ca un Python nativ int sau float; PdfName conține un șir name și este tipul folosit pentru cheile dicționarului în întregul model de obiecte de nivel scăzut — de exemplu, cheile Font și Resources din dicționarul de resurse al unei pagini. PdfNull reprezintă obiectul 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")

Valori de culoare

Color reprezintă o culoare RGBA cu proprietăți float r, g, b și a. În afară de constructorul cu două argumente plus alfa, expune un set complet de fabrici de culori numite — atât în minuscule (aqua(), blue(), azure(), red(), green(), yellow(), black(), white(), gray()) și PascalCase aliasuri (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()

Codificări de text și filtre de flux

EncodingType (WIN_ANSI, MAC_ROMAN, MAC_EXPERT, PDF_DOC, UNICODE) identifică o codificare de text, iar Encoding expune constantele de codificare corespunzătoare (UTF8, UTF16, LATIN1, WIN_ANSI) alături de o metodă encode(text, encoding_type) care returnează bytes codificat. FilterType (NONE, FLATE_DECODE, LZW_DECODE, DCT_DECODE, JPX_DECODE, CCITT_FAX_DECODE, JBIG2_DECODE) identifică filtrul de flux aplicat conținutului PDF comprimat.

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

Metadate XMP

XmpPacket este modelul în memorie pentru pachetul de metadate XMP al unui document — este tipul returnat de Document.xmp_metadata. Conține o colecție ordonată de fields (fiecare fiind un XmpField, XmpArray sau XmpProperty) și rezolvă prefixele de spațiu de nume printr-un XmpNamespaceProvider. Gettere și settere tipizate (get_value-style accesori precum get_bool, get_int, get_real, get_date, get_localized_text, get_array, și omologii lor set_*) citesc și scriu proprietăți individuale după prefixul de spațiu de nume sau URI și numele proprietății.

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 modelează o valoare structurată (rdf:parseType="Resource") cu propriul său tabel de căutare get(name), XmpArray modelează un tablou ordonat cu add(item) și remove(item), iar XmpProperty este o proprietate care poartă proprii săi calificatori add_qualifier/remove_qualifier. Toate cele patru împărtășesc același bloc de construcție XmpField pentru valori individuale.

Sfaturi și bune practici

• Citește Document.xmp_metadata pentru a obține XmpPacket documentului în loc să construiești unul de la zero — este deja populat din fișierul încărcat.
• Citește PdfNumber.value direct — conține deja Python int sau float nativ pe care l-ai transmis constructorului; nu există nicio metodă de conversie to_double() sau to_int().
• Preferă fabricile Color denumite (Color.red(), Color.Black() etc.) în locul tuplurilor r/g/b/a create manual pentru culorile comune — sunt mai ușor de înțeles la punctele de apel.
• Potrivește EncodingType pe care îl transmiți la Encoding.encode() cu codificarea pe care destinația (font, flux sau vizualizator) o așteaptă în mod real; nepotrivirile de codificare a textului PDF sunt o sursă comună de output distorsionat.
• Tratează PdfObjectRegistry și PdfObjectID ca tipuri de nivel scăzut, orientate către motor — majoritatea codului aplicației citește conținutul documentului prin Document și Page în loc să înregistreze obiecte direct.

Probleme comune

FAQ

Trebuie să construiesc eu PdfObjectID sau PdfObjectRegistry?

Rareori. Ele susțin procesul de serializare al motorului; majoritatea codului aplicației nu le instanțiază niciodată direct, cu excepția cazului în care lucrează cu modelul de obiecte de nivel scăzut.

Care este diferența dintre XmpField, XmpArray, XmpStruct și XmpProperty?

XmpField este o valoare scalară singulară. XmpArray este o listă ordonată de valori, XmpStruct este o grupare structurată (rdf:parseType="Resource") de câmpuri, și XmpProperty este o valoare care poartă, de asemenea, propriile calificative.

Cum pot obține metadatele XMP ale unui document?

Citește proprietatea xmp_metadata pe un Document încărcat — aceasta returnează un XmpPacket pe care îl poți interoga și actualiza la fața locului.

Fabricile de culoare cu litere mici și PascalCase sunt culori diferite?

Nu — Color.red() și Color.Red() sunt aliasuri care returnează aceeași culoare; ambele ortografii sunt oferite pentru comoditate.

API Reference Rezumat

Vezi și:

• Aspose.PDF for Python — Enterprise Documentation