Primitif Data dan Metadata XMP

Primitif Data dan Metadata XMP

Aspose.PDF FOSS untuk Python membangun API tingkat-tinggi — Document, Page, dan kelas anotasi serta formulir — di atas sekumpulan kecil tipe data primitif yang didefinisikan dalam aspose_pdf.engine.data. Anda jarang akan membuat sebagian besar ini secara langsung, tetapi mereka muncul terus-menerus sebagai tipe properti dan nilai kembali: kamus sumber daya halaman diindeks oleh nilai PdfName, warna adalah instance Color, dan Document.xmp_metadata mengembalikan sebuah XmpPacket. Panduan ini memperkenalkan primitif identitas objek, pembungkus nilai primitif, Color, enum pengkodean teks, dan model metadata XMP.

Identitas Objek dan Registri Objek

PdfObjectID mengidentifikasi objek tidak langsung dalam file PDF berdasarkan object_number dan generation_number. PdfObjectRegistry memberikan dan melacak pengenal ini saat objek diserialkan, dan PdfTrailerable adalah kontrak bersama untuk objek yang dapat menghasilkan kamus yang ditulis ke trailer 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)

Pembungkus Nilai Primitif

PdfNumber dan PdfName membungkus nilai PDF mentah dalam objek Python yang bertipe. PdfNumber menyimpan value numeriknya sebagai Python int atau float asli; PdfName menyimpan string name dan merupakan tipe yang digunakan untuk kunci kamus di seluruh model objek tingkat rendah — misalnya, kunci Font dan Resources pada kamus sumber daya halaman. PdfNull mewakili objek 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")

Nilai Warna

Color mewakili warna RGBA dengan properti float r, g, b, dan a. Selain konstruktor dua-argumen-plus-alpha, ia menyediakan satu set lengkap pabrik warna bernama — baik huruf kecil (aqua(), blue(), azure(), red(), green(), yellow(), black(), white(), gray()) dan 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()

Pengkodean teks dan filter aliran

EncodingType (WIN_ANSI, MAC_ROMAN, MAC_EXPERT, PDF_DOC, UNICODE) mengidentifikasi sebuah pengkodean teks, dan Encoding menampilkan konstanta pengkodean yang cocok (UTF8, UTF16, LATIN1, WIN_ANSI) bersama dengan metode encode(text, encoding_type) yang mengembalikan bytes yang telah dienkode. FilterType (NONE, FLATE_DECODE, LZW_DECODE, DCT_DECODE, JPX_DECODE, CCITT_FAX_DECODE, JBIG2_DECODE) mengidentifikasi filter aliran yang diterapkan pada konten PDF terkompresi.

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

Metadata XMP

XmpPacket adalah model dalam memori untuk paket metadata XMP dokumen — itu adalah tipe yang dikembalikan oleh Document.xmp_metadata. Ia menyimpan koleksi terurut dari fields (masing-masing berupa XmpField, XmpArray, atau XmpProperty) dan menyelesaikan prefiks namespace melalui sebuah XmpNamespaceProvider. Getter dan setter bertipe (get_value-style accessor seperti get_bool, get_int, get_real, get_date, get_localized_text, get_array, dan pasangan set_* mereka) membaca dan menulis properti individu berdasarkan prefiks namespace atau URI serta nama properti.

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 memodelkan nilai terstruktur (rdf:parseType="Resource") dengan pencarian get(name) miliknya, XmpArray memodelkan array terurut dengan add(item) dan remove(item), dan XmpProperty adalah properti yang membawa kualifier add_qualifier/remove_qualifiernya sendiri. Keempatnya berbagi blok bangunan XmpField yang sama untuk nilai individual.

Tips dan Praktik Terbaik

• Baca Document.xmp_metadata untuk mendapatkan XmpPacket dokumen alih-alih membuatnya dari nol — ia sudah terisi dari berkas yang dimuat.
• Baca PdfNumber.value secara langsung — ia sudah berisi Python int atau float asli yang Anda berikan ke konstruktor; tidak ada metode konversi to_double() atau to_int().
• Lebih pilih pabrik Color bernama (Color.red(), Color.Black(), dan seterusnya) daripada tuple buatan tangan r/g/b/a untuk warna umum — mereka lebih mudah dibaca pada tempat pemanggilan.
• Sesuaikan EncodingType yang Anda berikan ke Encoding.encode() dengan enkoding yang sebenarnya diharapkan oleh tujuan (font, stream, atau viewer); ketidakcocokan enkoding teks PDF adalah sumber umum output yang kacau.
• Anggap PdfObjectRegistry dan PdfObjectID sebagai tipe tingkat rendah yang berhadapan dengan mesin — kebanyakan kode aplikasi membaca konten dokumen melalui Document dan Page alih-alih mendaftarkan objek secara langsung.

Masalah Umum

FAQ

Apakah saya perlu membuat PdfObjectID atau PdfObjectRegistry sendiri?

Jarang. Mereka mendukung proses serialisasi mesin; kebanyakan kode aplikasi tidak pernah menginstansiasi mereka secara langsung kecuali sedang bekerja dengan model objek tingkat rendah.

Apa perbedaan antara XmpField, XmpArray, XmpStruct, dan XmpProperty?

XmpField adalah nilai skalar tunggal. XmpArray adalah daftar terurut nilai, XmpStruct adalah pengelompokan terstruktur (rdf:parseType="Resource") dari bidang, dan XmpProperty adalah nilai yang juga membawa kualifikasinya sendiri.

Bagaimana cara saya mendapatkan metadata XMP dokumen?

Baca properti xmp_metadata pada Document yang telah dimuat — properti ini mengembalikan XmpPacket yang dapat Anda kueri dan perbarui secara langsung.

Apakah pabrik Warna huruf kecil dan PascalCase menghasilkan warna yang berbeda?

Tidak — Color.red() dan Color.Red() adalah alias yang mengembalikan warna yang sama; kedua ejaan disediakan untuk kemudahan.

Ringkasan API Reference

Lihat Juga

• Aspose.PDF for Python — Enterprise Documentation