Cấu trúc nội bộ của Động cơ Xử lý PDF

Nội bộ Động cơ Xử lý PDF

Các lớp Document, Page và Annotation mà bạn dùng hàng ngày để xử lý PDF là một lớp mặt nạ trên một gói aspose_pdf.engine cấp thấp hơn. Động cơ thực hiện các cơ chế thực tế của PDF: mô hình đối tượng COS (Carousel Object Structure) mà mọi tệp PDF được xây dựng từ đó, bộ phân tách và bộ ghi chuyển đổi giữa các đối tượng COS và byte PDF, tổng hợp giao diện chú thích, raster hoá trang, các nội bộ codec phông chữ và hình ảnh, và các nguyên thủy mật mã phía sau việc mã hoá tài liệu và chữ ký số. Hầu hết các ứng dụng không bao giờ cần nhập trực tiếp từ aspose_pdf.engine — nhưng đó là nơi đúng để tìm khi bạn cần công cụ tùy chỉnh, kiểm tra PDF pháp y, hoặc hành vi mà API cấp cao không cung cấp.

Tạo Giao diện cho Một Chú thích Đơn lẻ

Các chú thích tương tác như hình vuông, vòng tròn và dấu không tự động chứa một luồng giao diện chuẩn (/AP /N). Gọi Annotation.generate_appearance sẽ kích hoạt các nội bộ tổng hợp giao diện của động cơ để tạo ra một luồng khi cần dựa trên các thuộc tính của chú thích.

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

Tạo Giao diện Hàng loạt trên Nhiều Trang và Tài liệu

AnnotationCollection.generate_appearances synthesizes appearances for every eligible annotation on a page in one call, skipping subtypes the engine doesn’t know how to render (such as 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 thực hiện điều tương tự trên mọi trang trong tài liệu, và là idempotent — lần gọi thứ hai sẽ không thực hiện gì khi các giao diện đã tồn tại:

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

Làm phẳng các chú thích thành nội dung trang tĩnh

Document.flatten() vẽ mọi hình ảnh của chú thích trực tiếp vào luồng nội dung của trang (như một lời gọi Do XObject) và sau đó loại bỏ đối tượng chú thích, vì vậy trang hiển thị giống hệt trong các trình xem bỏ qua hoàn toàn chú thích:

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

Sau lời gọi này, luồng nội dung của trang dài hơn so với trước (bây giờ nó chứa hình vuông được nhúng) và doc.pages[0].annotations không còn chứa chú thích đã được làm phẳng.

Suy xuất các khóa mã hoá dựa trên mật khẩu (Phiên bản 4 / AES-128)

EncryptionUtils thực thi việc suy xuất khóa và các primitive AES-CBC của trình xử lý bảo mật tiêu chuẩn PDF một cách trực tiếp, độc lập với Document API. Điều này hữu ích cho công cụ tùy chỉnh hoặc kiểm tra pháp y các PDF đã được mã hoá:

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

Mã hoá nội dung thô bằng AES-CBC

Đối với các nhu cầu cấp thấp, EncryptionUtils.encrypt_aes_cbc() và decrypt_aes_cbc() hoạt động trực tiếp trên bất kỳ khóa 16-, 24- hoặc 32-byte nào mà không qua quá trình suy xuất khóa dựa trên mật khẩu:

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

Mẹo và các thực hành tốt nhất

• Ưu tiên giao diện cấp cao Document, Page, và Annotation cho việc xử lý tài liệu hàng ngày. Gói aspose_pdf.engine là triển khai nội bộ mà các lớp này được xây dựng trên — chỉ sử dụng nó khi bạn cần công cụ tùy chỉnh, kiểm tra pháp y, hoặc hành vi mà giao diện không cung cấp.
• Khớp đối số revision với trình xử lý bảo mật mà bạn đang nhắm tới: compute_owner_key_v4/compute_user_key_v4 bao phủ các phiên bản 2–4 (RC4/AES 40-bit và 128-bit), trong khi compute_hash_v5 triển khai thuật toán Phiên bản 5/6 được AES-256 sử dụng. Trộn lẫn các phiên bản và độ dài khóa sẽ âm thầm tạo ra khóa sai.
• Document.generate_appearances và AnnotationCollection.generate_appearances là idempotent — gọi chúng một cách phòng ngừa trước khi render hoặc làm phẳng một tài liệu mà bạn không tự tạo.
• Document.flatten() là thao tác phá hủy: nó xóa mọi chú thích mà nó vẽ vào nội dung trang. Hoàn thành bất kỳ chỉnh sửa chú thích nào khác trước, hoặc làm việc trên một bản sao.
• Không phải mọi subtype của chú thích đều có bộ tổng hợp giao diện tích hợp — Text và Popup là những ví dụ phổ biến. Kiểm tra has_appearance sau khi gọi generate_appearance() thay vì giả định nó đã thành công.

Các vấn đề thường gặp

FAQ

Tôi có cần nhập từ aspose_pdf.engine cho việc xử lý tài liệu hàng ngày không?

Không. Các lớp Document, Page và Annotation bao phủ quy trình công việc tài liệu tiêu chuẩn. Lớp engine là nơi hành vi của các lớp này được triển khai, và nó hữu ích nhất cho công cụ tùy chỉnh hoặc kiểm tra nội bộ PDF một cách trực tiếp.

Sự khác biệt giữa Annotation.generate_appearance và AnnotationCollection.generate_appearances là gì?

Cái đầu tiên tạo ra một luồng hiển thị cho một chú thích duy nhất và trả về một bool. Cái thứ hai thực hiện cùng việc này cho mọi chú thích đủ điều kiện trong một bộ sưu tập (các chú thích của một trang, hoặc, thông qua Document.generate_appearances, mọi trang trong tài liệu) và trả về số lượng hiển thị mà nó đã tạo.

Tại sao các phương pháp suy xuất khóa lại nhận một đối số revision?

Trình xử lý bảo mật tiêu chuẩn PDF đã phát triển qua các phiên bản ISO 32000 — Phiên bản 2 sử dụng RC4 40-bit, Phiên bản 3/4 hỗ trợ RC4 128-bit hoặc AES, và Phiên bản 5/6 (được dùng cho AES-256) sử dụng một thuật toán băm hoàn toàn khác (compute_hash_v5). Đối số revision chọn phép suy xuất mà các phương thức EncryptionUtils thực hiện.

Tôi có thể kiểm tra hoặc xây dựng các đối tượng PDF thô một cách trực tiếp không?

Có. aspose_pdf.engine.cos cung cấp mô hình đối tượng COS — PdfObject, PdfDictionary, PdfArray, PdfStream, PdfName, và các kiểu liên quan — mà PdfCosWriter và PdfCosParser tuần tự hoá và phân tích từ các byte PDF.

Quá trình render trang sang hình ảnh diễn ra ở đâu?

Document.render_page trả về một RasterizedPage, một đối tượng cấp độ engine với các phương thức to_png(), to_tiff() và save() để chuyển một trang đã render thành tệp hình ảnh.

API Reference Tóm tắt

Xem thêm

• Aspose.PDF for Python — Enterprise Documentation