Dataprimtiver och XMP-metadata

Dataprimitiver och XMP-metadata

Aspose.PDF FOSS för Python bygger sin högre nivå API — Document, Page och annoterings- och formulärklasserna — ovanpå en liten uppsättning primitiva datatyper definierade i aspose_pdf.engine.data. Du kommer sällan att konstruera de flesta av dessa direkt, men de dyker upp konstant som egenskapstyper och returvärden: en sidas resurser-ordbok nyckelas av PdfName-värden, färger är Color-instanser, och Document.xmp_metadata returnerar en XmpPacket. Denna guide introducerar objektidentitetsprimitiverna, de primitiva värdeomslagen, Color, textkodningsenumren och XMP-metadata-modellen.

Objektidentitet och objektregistret

PdfObjectID identifierar ett indirekt objekt i en PDF-fil med dess object_number och generation_number. PdfObjectRegistry tilldelar och spårar dessa identifierare när objekt serialiseras, och PdfTrailerable är det gemensamma kontraktet för objekt som kan producera den ordbok som skrivs in i en 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)

Primitiva värdeomslag

PdfNumber och PdfName omsluter råa PDF-värden i typade Python-objekt. PdfNumber lagrar sitt numeriska value som en inbyggd Python int eller float; PdfName lagrar en name sträng och är den typ som används för nycklar i ordböcker genom hela låg-nivå-objektmodellen — till exempel Font och Resources nycklarna i en sidas resursordbok. PdfNull representerar PDF-null-objektet.

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

Färgvärden

Color representerar en RGBA-färg med r, g, b och a flyttalsattribut. Förutom två-argument-plus-alpha-konstruktorn exponerar den en komplett uppsättning namngivna färgfabriker — både gemener (aqua(), blue(), azure(), red(), green(), yellow(), black(), white(), gray()) och PascalCase alias (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()

Textkodningar och strömningsfilter

EncodingType (WIN_ANSI, MAC_ROMAN, MAC_EXPERT, PDF_DOC, UNICODE) identifierar en textkodning, och Encoding exponerar de matchande kodningskonstanterna (UTF8, UTF16, LATIN1, WIN_ANSI) samt en encode(text, encoding_type)-metod som returnerar den kodade bytes. FilterType (NONE, FLATE_DECODE, LZW_DECODE, DCT_DECODE, JPX_DECODE, CCITT_FAX_DECODE, JBIG2_DECODE) identifierar strömningsfiltret som tillämpas på komprimerat PDF-innehåll.

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 är in-minnesmodellen för ett dokuments XMP-metadata-paket — det är den typ som returneras av Document.xmp_metadata. Den innehåller en ordnad samling av fields (varje en XmpField, XmpArray eller XmpProperty) och löser namnrymdsprefix genom ett XmpNamespaceProvider. Typade getter- och setter-metoder (get_value-stil åtkomstfunktioner såsom get_bool, get_int, get_real, get_date, get_localized_text, get_array, och deras set_* motsvarigheter) läser och skriver enskilda egenskaper efter namnrymdsprefix eller URI och egenskapsnamn.

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 modellerar ett strukturerat (rdf:parseType="Resource") värde med sin egen get(name)-uppslagning, XmpArray modellerar en ordnad array med add(item) och remove(item), och XmpProperty är en egenskap som bär sina egna add_qualifier/remove_qualifier-kvalificerare. Alla fyra delar samma XmpField-byggsten för enskilda värden.

Tips och bästa praxis

• Läs Document.xmp_metadata för att få dokumentets XmpPacket snarare än att skapa en från grunden — den är redan ifylld från den laddade filen.
• Läs PdfNumber.value direkt — den innehåller redan den inbyggda Python int eller float som du skickade till konstruktorn; det finns ingen to_double() eller to_int() konverteringsmetod.
• Föredra de namngivna Color-fabrikerna (Color.red(), Color.Black() osv.) framför handgjorda r/g/b/a-tupler för vanliga färger — de är tydligare vid anrop.
• Matcha den EncodingType du skickar till Encoding.encode() med den kodning som destinationen (teckensnitt, ström eller visare) faktiskt förväntar sig; PDF-textkodningsmissmatchningar är en vanlig källa till förvrängd output.
• Behandla PdfObjectRegistry och PdfObjectID som lågnivå, motorn-inriktade typer — de flesta applikationskoder läser dokumentinnehåll via Document och Page snarare än att registrera objekt direkt.

Vanliga problem

FAQ

Behöver jag skapa PdfObjectID eller PdfObjectRegistry själv?

Sällan. De stödjer motorns serialiseringsprocess; de flesta applikationskoder instansierar dem aldrig direkt såvida de inte arbetar med lågnivåobjektmodellen.

Vad är skillnaden mellan XmpField, XmpArray, XmpStruct och XmpProperty?

XmpField är ett enskilt skalärt värde. XmpArray är en ordnad lista av värden, XmpStruct är en strukturerad (rdf:parseType="Resource") gruppering av fält, och XmpProperty är ett värde som också har sina egna kvalificerare.

Hur får jag ett dokuments XMP-metadata?

Läs egenskapen xmp_metadata på en inläst Document — den returnerar en XmpPacket som du kan fråga och uppdatera på plats.

Är de gemena och PascalCase Color-fabrikerna olika färger?

Nej — Color.red() och Color.Red() är alias som returnerar samma färg; båda stavningarna tillhandahålls för bekvämlighet.

API Reference Sammanfattning

Se även

• Aspose.PDF for Python — Enterprise Documentation