Chú thích PDF

Chú thích PDF

Page.annotations cung cấp một AnnotationCollection — một view có thể thay đổi, giống chuỗi, cho mọi chú thích trên một trang. Mỗi mục là một Annotation (hoặc các lớp con MarkupAnnotation / LinkAnnotation), và dữ liệu riêng theo loại phụ như các điểm quad, danh sách mực, hoặc màu sắc được đọc và ghi thông qua get_property() / set_property() thay vì các thuộc tính riêng biệt.

Thêm chú thích

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) tạo một chú thích mới và thêm nó vào trang. subtype chấp nhận một chuỗi đơn giản ("Text", "Square", "Highlight") hoặc một thành viên enum AnnotationType.

import aspose_pdf
from aspose_pdf import Document, AnnotationType

doc = Document()
doc.pages.add()
page = doc.pages[0]

# Plain string subtype
page.annotations.add("Text", (100, 100, 200, 200), "Hello")

# AnnotationType enum, with subtype-specific properties
page.annotations.add(
    AnnotationType.POLYGON,
    (0, 0, 10, 10),
    "",
    properties={"Vertices": [0, 0, 10, 0, 5, 10]},
)

Đọc và Cập nhật Thuộc tính

get_property(name, default) đọc một giá trị riêng theo loại phụ; set_property(name, value) ghi một giá trị, và việc đặt một thuộc tính thành None sẽ xóa nó khỏi dict properties của chú thích.

doc = Document()
doc.pages.add()
page = doc.pages[0]

ann = page.annotations.add(
    "Square", (0, 0, 50, 50), "x", properties={"C": [1, 0, 0]},
)
ann.set_property("IC", [0, 0, 1])
print(page.annotations[0].get_property("IC"))  # [0, 0, 1]

ann.set_property("C", None)  # removes the "C" entry entirely
print("C" in page.annotations[0].properties)  # False

Đặt tên cho chú thích bằng AnnotationName

Tên PDF (ví dụ: mục Name của chú thích Stamp) được đánh dấu khác biệt so với chuỗi thông thường bằng cách sử dụng AnnotationName, một lớp con str của aspose_pdf.engine.cos. Giá trị được lưu theo cách này vẫn so sánh bằng với một chuỗi thông thường.

from aspose_pdf.engine.cos import AnnotationName

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add(
    "Stamp", (10, 10, 110, 60), "",
    properties={"Name": AnnotationName("Approved")},
)

Chèn, Xóa và Xóa sạch

insert(index, subtype, rect, contents, title, appearance_normal, properties) đặt một chú thích mới tại vị trí cụ thể; delete(index) xóa một chú thích theo chỉ mục (ném IndexError khi chỉ mục vượt quá phạm vi); clear() xóa tất cả các chú thích khỏi trang.

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add("Text", (0, 0, 100, 100), "A")
page.annotations.add("Text", (200, 200, 300, 300), "C")
page.annotations.insert(1, "Text", (100, 100, 200, 200), "B")
# order is now: A, B, C

page.annotations.delete(1)   # removes "B"
page.annotations.clear()     # removes everything remaining

Tạo hiển thị chú thích

Annotation.generate_appearance(force) xây dựng luồng hiển thị /AP /N cho một chú thích và trả về True khi có bộ dựng cho kiểu phụ đó; AnnotationCollection.generate_appearances(force) thực hiện cùng việc cho mọi chú thích trên trang trong một lời gọi và trả về số lượng chú thích thực sự được tạo (các kiểu phụ không được hỗ trợ sẽ bị bỏ qua).

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

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

Kiểu phụ và Cờ của chú thích

AnnotationType liệt kê các tên kiểu phụ chuẩn PDF 32000-1:2008 (Bảng 169): TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, POLY_LINE, HIGHLIGHT, UNDERLINE, SQUIGGLY, STRIKE_OUT, STAMP, CARET, INK, POPUP, FILE_ATTACHMENT, SOUND, MOVIE, WIDGET, SCREEN, PRINTER_MARK, TRAP_NET, WATERMARK, và REDACT.

AnnotationFlags là một IntFlag bao phủ hành vi hiển thị/tương tác của chú thích: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED, và TOGGLE_NO_VIEW.

Bản thử nghiệm: Ghi chú 3D

PDF3DAnnotation, PDF3DArtwork, PDF3DContent, và PDF3DView mô hình tác phẩm 3D được gắn vào một trang — một PDF3DAnnotation có một rect: Rectangle, một artwork: PDF3DArtwork, và một background_color: Color tùy chọn. PDF3DArtwork.add_view() đăng ký một PDF3DView, mỗi cái mang một render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) và một lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM). Chuỗi tài liệu (docstring) của thư viện đánh dấu PDF3DAnnotation là một “minimal annotation wrapper for prerelease imports” — coi bề mặt này là giai đoạn đầu chứ không phải một API tác giả 3D đã hoàn thiện.

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

• Ưu tiên các thành viên enum AnnotationType hơn các chuỗi subtype thô khi giá trị cũng cần được so sánh hoặc phân nhánh ở nơi khác trong mã của bạn.
• Gọi set_property(name, None) để xóa một thuộc tính hoàn toàn thay vì để lại giá trị lỗi thời — mục sẽ biến mất hoàn toàn khỏi properties.
• Tạo hàng loạt các dạng xuất hiện bằng AnnotationCollection.generate_appearances thay vì lặp generate_appearance() cho mỗi ghi chú; nó trả về số lượng thực tế đã tạo nên bạn có thể phát hiện các subtype bị bỏ qua/không được hỗ trợ.
• delete() và việc chỉ mục vào page.annotations đều dựa trên chỉ số 0; hãy xác thực một chỉ số trước khi gọi delete() nếu nó đến từ đầu vào của người dùng, vì chỉ số ngoài phạm vi sẽ gây ra IndexError.
• Bao bọc các giá trị tên PDF (như Stamp’s Name) trong AnnotationName để chúng được truyền đi/đến lại dưới dạng tên PDF thay vì chuỗi văn bản thuần.

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

FAQ

Làm sao để thêm chú thích bình luận dạng văn bản thuần?

Gọi page.annotations.add("Text", (x0, y0, x1, y1), "comment text"). Bộ bốn số là hình chữ nhật của chú thích trên trang.

Sự khác biệt giữa Annotation, MarkupAnnotation và LinkAnnotation là gì?

Annotation là chế độ xem trực tiếp được trả về cho bất kỳ chú thích nào trên trang. MarkupAnnotation là cơ sở cho các kiểu phụ thuộc kiểu đánh dấu (đánh dấu, ghi chú văn bản, hình dạng) và LinkAnnotation được giữ cho các chú thích kiểu liên kết; hiện tại cả hai đều cung cấp cùng một giao diện phương thức/thuộc tính như Annotation.

Tôi có thể xóa một thuộc tính duy nhất mà không xóa toàn bộ chú thích không?

Có — gọi annotation.set_property(name, None); chú thích vẫn nguyên vẹn, chỉ mục nhập đó bị xóa khỏi properties.

Liệu AnnotationCollection.generate_appearances có thất bại nếu một kiểu phụ không được hỗ trợ không?

Không. Nó bỏ qua các kiểu phụ không có bộ dựng hình xuất hiện tích hợp và trả về số lượng chú thích mà nó thực sự đã tạo ra một hình xuất hiện cho chúng.

Các lớp chú thích 3D có sẵn sàng cho môi trường sản xuất không?

PDF3DAnnotation và các kiểu liên quan được tài liệu mô tả như một lớp bao bọc tối thiểu cho các import trước phát hành — hãy kiểm tra hành vi trên trình xem PDF mục tiêu của bạn trước khi dựa vào chúng cho nội dung 3D trong môi trường sản xuất.

Tóm tắt API Reference

Xem thêm

• Aspose.PDF for Python — Enterprise Documentation