Primitivi di dati e metadati XMP

Primitive di Dati e Metadati XMP

Aspose.PDF FOSS per Python costruisce i suoi API di livello superiore — Document, Page e le classi di annotazione e modulo — sopra un piccolo insieme di tipi di dati primitivi definiti in aspose_pdf.engine.data. Raramente costruirai direttamente la maggior parte di questi, ma compaiono costantemente come tipi di proprietà e valori di ritorno: il dizionario delle risorse di una pagina è indicizzato da valori PdfName, i colori sono istanze Color, e Document.xmp_metadata restituisce un XmpPacket. Questa guida introduce le primitive di identità degli oggetti, i wrapper di valori primitivi, Color, le enumerazioni di codifica del testo e il modello di metadati XMP.

Identità degli oggetti e registro degli oggetti

PdfObjectID identifica un oggetto indiretto in un file PDF tramite il suo object_number e generation_number. PdfObjectRegistry assegna e traccia questi identificatori man mano che gli oggetti vengono serializzati, e PdfTrailerable è il contratto condiviso per gli oggetti che possono produrre il dizionario scritto nel trailer di un 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 di valori primitivi

PdfNumber e PdfName avvolgono valori PDF grezzi in oggetti Python tipizzati. PdfNumber conserva il suo value numerico come un Python nativo int o float; PdfName contiene una stringa name ed è il tipo usato per le chiavi del dizionario in tutto il modello di oggetti di basso livello — ad esempio, le chiavi Font e Resources nel dizionario delle risorse di una pagina. PdfNull rappresenta l’oggetto 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 di colore

Color rappresenta un colore RGBA con le proprietà float r, g, b e a. Oltre al costruttore a due argomenti più alfa, espone un set completo di factory di colore nominate — sia in minuscolo (aqua(), blue(), azure(), red(), green(), yellow(), black(), white(), gray()) e alias 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()

Codifiche di testo e filtri di flusso

EncodingType (WIN_ANSI, MAC_ROMAN, MAC_EXPERT, PDF_DOC, UNICODE) identifica una codifica di testo, e Encoding espone le costanti di codifica corrispondenti (UTF8, UTF16, LATIN1, WIN_ANSI) insieme a un metodo encode(text, encoding_type) che restituisce il bytes codificato. FilterType (NONE, FLATE_DECODE, LZW_DECODE, DCT_DECODE, JPX_DECODE, CCITT_FAX_DECODE, JBIG2_DECODE) identifica il filtro di flusso applicato al contenuto PDF compresso.

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

Metadati XMP

XmpPacket è il modello in memoria per il pacchetto di metadati XMP di un documento — è il tipo restituito da Document.xmp_metadata. Contiene una collezione ordinata di fields (ognuno un XmpField, XmpArray o XmpProperty) e risolve i prefissi di namespace tramite un XmpNamespaceProvider. Getter e setter tipizzati (get_value-style accessors come get_bool, get_int, get_real, get_date, get_localized_text, get_array, e le loro controparti set_*) leggono e scrivono proprietà individuali per prefisso di namespace o URI e nome della proprietà.

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 modella un valore strutturato (rdf:parseType="Resource") con il proprio lookup get(name), XmpArray modella un array ordinato con add(item) e remove(item), e XmpProperty è una proprietà che porta i propri qualificatori add_qualifier/remove_qualifier. Tutti e quattro condividono lo stesso blocco costruttivo XmpField per i valori individuali.

Suggerimenti e migliori pratiche

• Leggi Document.xmp_metadata per ottenere il XmpPacket del documento invece di crearne uno da zero — è già popolato dal file caricato.
• Leggi PdfNumber.value direttamente — contiene già il nativo Python int o float che hai passato al costruttore; non esiste alcun metodo di conversione to_double() o to_int().
• Preferisci le factory Color nominate (Color.red(), Color.Black(), e così via) rispetto alle tuple r/g/b/a fatte a mano per i colori comuni — risultano più leggibili nei punti di chiamata.
• Fai corrispondere il EncodingType che passi a Encoding.encode() con la codifica che la destinazione (font, stream o visualizzatore) si aspetta realmente; le discrepanze di codifica del testo PDF sono una fonte comune di output illeggibile.
• Considera PdfObjectRegistry e PdfObjectID come tipi a basso livello, rivolti al motore — la maggior parte del codice dell’applicazione legge il contenuto del documento tramite Document e Page anziché registrare gli oggetti direttamente.

Problemi comuni

FAQ

Devo costruire PdfObjectID o PdfObjectRegistry da solo?

Raramente. Supportano il processo di serializzazione del motore; la maggior parte del codice dell’applicazione non li istanzia mai direttamente, a meno che non lavori con il modello di oggetti a basso livello.

Qual è la differenza tra XmpField, XmpArray, XmpStruct e XmpProperty?

XmpField è un valore scalare singolo. XmpArray è un elenco ordinato di valori, XmpStruct è un raggruppamento strutturato (rdf:parseType="Resource") di campi, e XmpProperty è un valore che porta anche i propri qualificatori.

Come posso ottenere i metadati XMP di un documento?

Leggi la proprietà xmp_metadata su un Document caricato — restituisce un XmpPacket che puoi interrogare e aggiornare sul posto.

Le factory di colore in minuscolo e PascalCase sono colori diversi?

No — Color.red() e Color.Red() sono alias che restituiscono lo stesso colore; entrambe le scritture sono fornite per comodità.

API Reference Riepilogo

Vedi anche

• Aspose.PDF for Python — Enterprise Documentation