数据原语和 XMP 元数据

数据原语和 XMP 元数据

Aspose.PDF FOSS for Python 在 aspose_pdf.engine.data 中定义的一小套原始数据类型之上，构建其更高层的 API —— Document、Page 以及注释和表单类。您很少会直接构造其中的大多数，但它们会不断出现为属性类型和返回值：页面的资源字典以 PdfName 值为键，颜色是 Color 实例，而 Document.xmp_metadata 返回一个 XmpPacket。本指南将介绍对象标识原语、原始值包装器、Color、文本编码枚举以及 XMP 元数据模型。

对象标识和对象注册表

PdfObjectID 通过其 object_number 和 generation_number 来标识 PDF 文件中的间接对象。PdfObjectRegistry 在对象序列化时分配并跟踪这些标识符，而 PdfTrailerable 则是能够生成写入 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)

原始值包装器

PdfNumber 和 PdfName 将原始 PDF 值包装为类型化的 Python 对象。PdfNumber 将其数值 value 以本机 Python int 或 float 的形式保存；PdfName 保存一个 name 字符串，并且是低层对象模型中用于字典键的类型——例如页面资源字典上的 Font 和 Resources 键。PdfNull 表示 PDF 的 null 对象。

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

颜色值

Color 表示具有 r、g、b 和 a 浮点属性的 RGBA 颜色。除了两个参数加 alpha 的构造函数外，它还提供了一整套具名颜色工厂——小写形式（aqua()、blue()、azure()、red()、green()、yellow()、black()、white()、gray()）以及 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()

文本编码和流过滤器

EncodingType（WIN_ANSI、MAC_ROMAN、MAC_EXPERT、PDF_DOC、UNICODE）用于标识一种文本编码，Encoding 则公开匹配的编码常量（UTF8、UTF16、LATIN1、WIN_ANSI），并提供一个 encode(text, encoding_type) 方法返回已编码的 bytes。FilterType（NONE、FLATE_DECODE、LZW_DECODE、DCT_DECODE、JPX_DECODE、CCITT_FAX_DECODE、JBIG2_DECODE）用于标识应用于压缩 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

XMP 元数据

XmpPacket 是文档 XMP 元数据包的内存模型——它是由 Document.xmp_metadata 返回的类型。它持有一个有序的 fields 集合（每个都是 XmpField、XmpArray 或 XmpProperty），并通过 XmpNamespaceProvider 解析命名空间前缀。类型化的 getter 和 setter（如 get_value 风格的访问器，包括 get_bool、get_int、get_real、get_date、get_localized_text、get_array，以及它们的 set_* 对应项）可按命名空间前缀或 URI 以及属性名读取和写入单个属性。

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 对结构化的（rdf:parseType="Resource"）值进行建模，拥有自己的 get(name) 查找表，XmpArray 对有序数组进行建模，具备 add(item) 和 remove(item)，而 XmpProperty 是携带自身 add_qualifier/remove_qualifier 限定符的属性。四者均共享相同的 XmpField 构件来表示单个值。

技巧与最佳实践

• 读取 Document.xmp_metadata 以获取文档的 XmpPacket，而不是从头构建——它已经从加载的文件中填充完毕。
• 直接读取 PdfNumber.value — 它已经包含了你在构造函数中传入的本机 Python int 或 float；没有 to_double() 或 to_int() 转换方法。
• 在常用颜色的情况下，优先使用具名的 Color 工厂（Color.red()、Color.Black() 等）而不是手工编写的 r/g/b/a 元组 — 它们在调用处更易读。
• 将你传递给 EncodingType 的 Encoding.encode() 与目标（字体、流或查看器）实际期望的编码匹配；PDF 文本编码不匹配是输出乱码的常见原因。
• 将 PdfObjectRegistry 和 PdfObjectID 视为低层、面向引擎的类型 — 大多数应用代码通过 Document 和 Page 读取文档内容，而不是直接注册对象。

常见问题

FAQ

我需要自行构造 PdfObjectID 或 PdfObjectRegistry 吗？

很少。它们支持引擎的序列化过程；除非在处理低层对象模型，否则大多数应用代码从不直接实例化它们。

在 XmpField、XmpArray、XmpStruct 和 XmpProperty 之间有什么区别？

XmpField 是单个标量值。XmpArray 是有序的值列表，XmpStruct 是结构化的（rdf:parseType="Resource"）字段分组，而 XmpProperty 是一个同时携带自身限定符的值。

如何获取文档的 XMP 元数据？

读取已加载的 Document 上的 xmp_metadata 属性——它返回一个可以直接查询和更新的 XmpPacket。

小写的和 PascalCase Color 工厂产生的颜色不同吗？

不——Color.red() 和 Color.Red() 是返回相同颜色的别名；提供两种拼写仅为方便。

API Reference 摘要

另请参阅

• Aspose.PDF for Python — Enterprise Documentation