Aspose.PDF FOSS
Developer Guide
PDF 处理引擎内部

PDF 处理引擎内部

PDF 处理引擎内部

Document、Page 和 Annotation 类是您日常 PDF 处理使用的外观层，背后是更低层的 aspose_pdf.engine 包。引擎实现了实际的 PDF 机制：每个 PDF 文件都基于的 COS（Carousel Object Structure）对象模型、在 COS 对象与 PDF 字节之间转换的解析器和写入器、注释外观合成、页面光栅化、字体和图像编解码器内部实现，以及文档加密和数字签名背后的加密原语。大多数应用程序从不需要直接导入 aspose_pdf.engine——但当您需要自定义工具、法医 PDF 检查或高层 API 未公开的行为时，这里是正确的查找位置。

为单个注释生成外观

交互式注释（如方框、圆形和印章）不会自动携带普通外观流（/AP /N）。调用 Annotation.generate_appearance 会触发引擎的外观合成内部机制，根据注释属性按需构建该流。

from aspose_pdf import Document

doc = Document()
doc.pages.add()
ann = doc.pages[0].annotations.add(
    "Square", (100, 100, 200, 200), "", properties={"C": [1, 0, 0], "IC": [0, 1, 0]}
)

print(ann.has_appearance)  # False -- no appearance stream yet
ann.generate_appearance()
print(ann.has_appearance)  # True -- the engine synthesised one
print(b"1 0 0 RG" in ann.appearance_normal)  # True -- red stroke operator
print(b"0 1 0 rg" in ann.appearance_normal)  # True -- green fill operator

跨页面和文档批量生成外观

AnnotationCollection.generate_appearances 在一次调用中为页面上每个符合条件的注释合成外观，跳过引擎不知道如何渲染的子类型（例如 Text）：

from aspose_pdf import Document

doc = Document()
doc.pages.add()
page = doc.pages[0]
page.annotations.add("Square", (0, 0, 50, 50), "")
page.annotations.add("Circle", (60, 0, 110, 50), "")
page.annotations.add("Text", (0, 60, 20, 80), "")  # unsupported subtype -> skipped

print(page.annotations.generate_appearances())  # 2

Document.generate_appearances 在文档的每一页上执行相同操作，且具备幂等性——一旦外观已存在，第二次调用将不产生任何作用：

from aspose_pdf import Document

doc = Document()
doc.pages.add()
doc.pages.add()
doc.pages[0].annotations.add("Square", (0, 0, 50, 50), "")
doc.pages[1].annotations.add(
    "Line", (0, 0, 50, 50), "", properties={"L": [0, 0, 50, 50]}
)

print(doc.generate_appearances())  # 2 -- one per page
print(doc.generate_appearances())  # 0 -- already generated, no-op

将注释展平为静态页面内容

Document.flatten() 将每个注释的外观直接绘制到其页面的内容流中（作为 Do XObject 调用），随后移除注释对象本身，因此在完全忽略注释的查看器中页面呈现完全相同：

from aspose_pdf import Document

doc = Document()
doc.pages.add()
doc.pages[0].annotations.add(
    "Square", (100, 100, 200, 200), "", properties={"C": [0, 0, 0]}
)

doc.flatten()

调用此操作后，页面的内容流比之前更长（现在包含了内联的方形），且 doc.pages[0].annotations 不再包含已展平的注释。

派生基于密码的加密密钥（修订版 4 / AES-128）

EncryptionUtils 直接实现 PDF 标准安全处理程序的密钥派生和 AES-CBC 原语，独立于 Document API。这对于自定义工具或对加密 PDF 进行取证检查非常有用：

import os
from aspose_pdf.engine.encryption import EncryptionUtils

file_id = os.urandom(16)
user_pwd = "mypassword"

# Derive the owner (O) and user (U) key material for Revision 4 (128-bit AES)
o_value = EncryptionUtils.compute_owner_key_v4("owner", user_pwd, 16, 4)
u_value, enc_key = EncryptionUtils.compute_user_key_v4(
    user_pwd, o_value, -4, file_id, 16, 4
)

# Encrypt data with the derived file-encryption key
plaintext = b"Confidential PDF content"
ciphertext = EncryptionUtils.encrypt_aes_cbc(enc_key, plaintext)

# Re-derive the key from the password before trusting it to decrypt
verified_key = EncryptionUtils.verify_password_v4(
    user_pwd, u_value, o_value, -4, file_id, 16, 4
)
print(verified_key is not None)  # True -- password matches

decrypted = EncryptionUtils.decrypt_aes_cbc(verified_key, ciphertext)
print(decrypted == plaintext)  # True

使用 AES-CBC 加密原始内容

对于底层需求，EncryptionUtils.encrypt_aes_cbc() 和 decrypt_aes_cbc() 可直接在任意 16、24 或 32 字节密钥上工作，完全不经过基于密码的密钥派生：

import os
from aspose_pdf.engine.encryption import EncryptionUtils

key = os.urandom(32)  # AES-256; 16 and 24-byte keys are also accepted
plaintext = b"Hello, PDF AES 256!"

ciphertext = EncryptionUtils.encrypt_aes_cbc(key, plaintext)
decrypted = EncryptionUtils.decrypt_aes_cbc(key, ciphertext)
print(decrypted == plaintext)  # True

技巧与最佳实践

  • 在日常文档处理时，优先使用高层的 Document、Page 和 Annotation 门面。aspose_pdf.engine 包是这些类所基于的内部实现——只有在需要自定义工具、取证检查或门面未公开的行为时才使用它。
  • 将 revision 参数与您所针对的安全处理程序匹配：compute_owner_key_v4/compute_user_key_v4 覆盖第 2–4 版（40 位和 128 位 RC4/AES），而 compute_hash_v5 实现了 AES-256 使用的第 5/6 版算法。混用版本和密钥长度会在不知情的情况下产生错误的密钥。
  • Document.generate_appearances 和 AnnotationCollection.generate_appearances 是幂等的——在渲染或扁平化您未自行创建的文档之前，建议防御性地调用它们。
  • Document.flatten() 具有破坏性：它会将所有注释从页面内容中移除。请先完成其他注释的编辑，或在副本上进行操作。
  • 并非所有注释子类型都内置外观合成器——Text 和 Popup 是常见的例子。调用 generate_appearance() 后请检查 has_appearance，不要默认它已成功。

常见问题

问题原因修复
EncryptionUtils.encrypt_aes_cbc/decrypt_aes_cbc 抛出 “AES key must be 16, 24, or 32 bytes” 错误提供了长度无效的密钥使用 os.urandom(16)、os.urandom(24) 或 os.urandom(32) 生成密钥
EncryptionUtils.verify_password_v4 返回 None 而不是抛出异常提供的密码与文档派生的 U/O 值不匹配在将结果传递给 decrypt_aes_cbc 之前，明确检查 None
Annotation.generate_appearance 返回 False注释的子类型没有内置的外观合成器（例如 Text 或 Popup）提供您自己的 appearance_normal 字节，或接受查看器的默认渲染
对 Document.generate_appearances 的第二次调用返回 0此调用是幂等的——已拥有 has_appearance == True 的注释会被跳过预期行为，而非错误

FAQ

日常文档处理是否需要从 aspose_pdf.engine 导入？

不。Document、Page 和 Annotation 类覆盖了标准文档工作流。引擎层是实现这些类行为的地方，最适合用于自定义工具或直接检查 PDF 内部。

Annotation.generate_appearance 和 AnnotationCollection.generate_appearances 有什么区别？

第一个为单个注释合成外观流并返回一个 bool。第二个对集合中每个符合条件的注释（页面的注释，或者通过 Document.generate_appearances 对文档的每一页）执行相同操作，并返回它创建的外观数量。

为什么密钥派生方法需要一个 revision 参数？

PDF 标准安全处理程序在 ISO 32000 的各个版本中不断演进——第 2 版使用 40 位 RC4，第 3/4 版支持 128 位 RC4 或 AES，而第 5/6 版（用于 AES-256）则完全使用不同的散列算法（compute_hash_v5）。revision 参数决定 EncryptionUtils 方法执行哪种派生。

我可以直接检查或构建原始 PDF 对象吗？

是的。aspose_pdf.engine.cos 暴露了 COS 对象模型——PdfObject、PdfDictionary、PdfArray、PdfStream、PdfName 以及相关类型——这些类型由 PdfCosWriter 和 PdfCosParser 序列化为 PDF 字节并从中解析。

页面转图像的渲染在哪里进行？

Document.render_page 返回一个 RasterizedPage，这是一个引擎级对象，具有 to_png()、to_tiff() 和 save() 方法，用于将渲染后的页面转换为图像文件。

API Reference 摘要

类 / 方法描述
Annotation.generate_appearance(force) -> bool按需合成单个注释的常规外观流
AnnotationCollection.generate_appearances(force) -> int批量生成页面上所有符合条件的注释的外观
Document.generate_appearances(force) -> int批量生成文档中所有符合条件的注释的外观
Document.flatten() -> Document将注释外观内联到页面内容中并删除注释
Document.render_page(page_index, dpi, scale, background, antialias) -> RasterizedPage通过引擎的渲染管线对页面进行光栅化
RasterizedPage以打包 RGB 格式渲染的页面，包含 to_png()、to_tiff() 和 save()
GeneratedAppearance外观合成的内部结果：内容字节以及任何所需的 ExtGState/字体资源
EncryptionUtilsAES-CBC/RC4 加密和 PDF 标准安全处理程序密钥派生（修订版 2–6）
PdfObject每个 COS（Carousel Object Structure）对象的抽象基类
PdfDictionary / PdfArray / PdfStream构成低层文档树的具体 COS 容器类型
PdfName / PdfNumber / PdfString / PdfBoolean / PdfNull原始 COS 值类型
PdfIndirectReference一个指向另一个对象的 COS 间接引用（n g R）
PdfCosWriter将内存中的 COS PdfDocument 序列化为 PDF 字节
PdfCosParser / LazyPdfObjectStore将 PDF 字节解析为 COS 对象，并按需实例化它们
IncrementalUpdate / IncrementalWriter向现有 PDF 追加增量更新段，而不是重新写入
SimplePdf原生-Python 低层文档表示，高层 Document API 基于其构建
TextFragmentAbsorber / TextFragmentCollection在 SimplePdf 实例上进行低层次的文本片段提取
ImagePlacementAbsorber / ImagePlacement定位、保存、替换或隐藏页面上放置的光栅图像
SigningUtils生成自签名证书以及用于数字签名的 PKCS#7/CAdES 签名
DssMaterial / ChainResult / RevocationResult / TimestampInfo签名验证支持：DSS 材料、证书链结果、吊销检查以及 RFC 3161 时间戳验证
StandardFonts14 种 PDF 标准字体的度量和编码
CidTextCodec对复合（Type0）字体的 show-strings 进行编码和解码
Shading在轴向、径向和基于函数的着色中采样 RGB 颜色
Color / Matrix在整个引擎中使用的底层颜色和二维仿射变换原语

另请参阅

 中文