Prymitywy danych i metadane XMP

Prymitywy danych i metadane XMP

Aspose.PDF FOSS dla Python buduje swoje wyższe poziomy API — Document, Page oraz klasy adnotacji i formularzy — na bazie niewielkiego zestawu prymitywnych typów danych zdefiniowanych w aspose_pdf.engine.data. Rzadko będziesz konstruować większość z nich bezpośrednio, ale pojawiają się nieustannie jako typy właściwości i wartości zwracane: słownik zasobów strony jest indeksowany wartościami PdfName, kolory są instancjami Color, a Document.xmp_metadata zwraca XmpPacket. Ten przewodnik wprowadza prymitywy tożsamości obiektów, opakowania wartości prymitywnych, Color, wyliczenia kodowania tekstu oraz model metadanych XMP.

Tożsamość obiektu i rejestr obiektów

PdfObjectID identyfikuje pośredni obiekt w pliku PDF za pomocą jego object_number i generation_number. PdfObjectRegistry przydziela i śledzi te identyfikatory podczas serializacji obiektów, a PdfTrailerable jest wspólnym kontraktem dla obiektów, które mogą wygenerować słownik zapisywany w trailerze 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)

Opakowania wartości prymitywnych

PdfNumber i PdfName opakowują surowe wartości PDF w typowane obiekty Python. PdfNumber przechowuje swoją numeryczną value jako natywny Python int lub float; PdfName przechowuje ciąg name i jest typem używanym dla kluczy słownika w całym niskopoziomowym modelu obiektów — na przykład klucze Font i Resources w słowniku zasobów strony. PdfNull reprezentuje obiekt 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")

Wartości kolorów

Color reprezentuje kolor RGBA z właściwościami zmiennoprzecinkowymi r, g, b i a. Oprócz konstruktora przyjmującego dwa argumenty plus alfa, udostępnia pełny zestaw nazwanych fabryk kolorów — zarówno małe litery (aqua(), blue(), azure(), red(), green(), yellow(), black(), white(), gray()) jak i aliasy 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()

Kodowania tekstu i filtry strumieniowe

EncodingType (WIN_ANSI, MAC_ROMAN, MAC_EXPERT, PDF_DOC, UNICODE) określa kodowanie tekstu, a Encoding udostępnia odpowiadające stałe kodowania (UTF8, UTF16, LATIN1, WIN_ANSI) wraz z metodą encode(text, encoding_type), która zwraca zakodowane bytes. FilterType (NONE, FLATE_DECODE, LZW_DECODE, DCT_DECODE, JPX_DECODE, CCITT_FAX_DECODE, JBIG2_DECODE) określa filtr strumienia stosowany do skompresowanej zawartości PDF.

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

Metadane XMP

XmpPacket jest modelem w pamięci dla pakietu metadanych XMP dokumentu — jest to typ zwracany przez Document.xmp_metadata. Przechowuje uporządkowaną kolekcję fields (każdy z nich to XmpField, XmpArray lub XmpProperty) i rozwiązuje prefiksy przestrzeni nazw za pomocą XmpNamespaceProvider. Typowane gettery i settery (akcesory w stylu get_value, takie jak get_bool, get_int, get_real, get_date, get_localized_text, get_array, oraz ich odpowiedniki set_*) odczytują i zapisują poszczególne właściwości według prefiksu przestrzeni nazw lub URI oraz nazwy właściwości.

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 modeluje ustrukturyzowaną wartość (rdf:parseType="Resource") z własnym słownikiem get(name), XmpArray modeluje uporządkowaną tablicę z add(item) i remove(item), a XmpProperty jest właściwością, która posiada własne kwalifikatory add_qualifier/remove_qualifier. Wszystkie cztery współdzielą ten sam element konstrukcyjny XmpField dla poszczególnych wartości.

Wskazówki i najlepsze praktyki

• Odczytaj Document.xmp_metadata, aby uzyskać XmpPacket dokumentu, zamiast tworzyć go od zera — jest już wypełniony z załadowanego pliku.
• Odczytaj PdfNumber.value bezpośrednio — już zawiera natywne Python int lub float, które przekazałeś do konstruktora; nie ma metody konwersji to_double() ani to_int().
• Preferuj nazwane fabryki Color (Color.red(), Color.Black() i tak dalej) zamiast ręcznie tworzonych krotek r/g/b/a dla typowych kolorów — są one czytelniejsze w miejscach wywołań.
• Dopasuj EncodingType przekazywany do Encoding.encode() do kodowania, którego faktycznie oczekuje odbiorca (czcionka, strumień lub przeglądarka); niezgodności kodowania tekstu PDF są częstym źródłem zniekształconego wyjścia.
• Traktuj PdfObjectRegistry i PdfObjectID jako typy niskiego poziomu, skierowane do silnika — większość kodu aplikacji odczytuje zawartość dokumentu przez Document i Page, a nie rejestrując obiekty bezpośrednio.

Typowe problemy

FAQ

Czy muszę samodzielnie tworzyć PdfObjectID lub PdfObjectRegistry?

Rzadko. Są one wsparciem procesu serializacji silnika; większość kodu aplikacji nigdy nie tworzy ich bezpośrednio, chyba że pracuje z modelem obiektów niskiego poziomu.

Jaka jest różnica między XmpField, XmpArray, XmpStruct i XmpProperty?

XmpField jest pojedynczą wartością skalarą. XmpArray jest uporządkowaną listą wartości, XmpStruct jest strukturalnym (rdf:parseType="Resource") grupowaniem pól, a XmpProperty jest wartością, która dodatkowo posiada własne kwalifikatory.

Jak mogę uzyskać metadane XMP dokumentu?

Odczytaj właściwość xmp_metadata w załadowanym Document — zwraca ona XmpPacket, którą możesz odpytać i zaktualizować w miejscu.

Czy fabryki kolorów w małych literach i PascalCase to różne kolory?

Nie — Color.red() i Color.Red() są aliasami, które zwracają ten sam kolor; obie pisowni są dostępne dla wygody.

API Reference Podsumowanie

Zobacz także

• Aspose.PDF for Python — Enterprise Documentation