הערות PDF

הערות PDF

Page.annotations חושף AnnotationCollection — תצוגה ניתנת לשינוי, בדומה לרצף, על כל ההערה בעמוד. כל ערך הוא Annotation (או תתי-המחלקות MarkupAnnotation / LinkAnnotation), ונתונים ספציפיים לתת-סוג כגון נקודות קווד, רשימות דיו, או צבעים נקראים ונכתבים דרך get_property() / set_property() במקום תכונות ייעודיות.

הוספת הערות

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) יוצר הערה חדשה ומוסיף אותה לעמוד. subtype מקבל מחרוזת רגילה ("Text", "Square", "Highlight") או חבר 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]},
)

קריאה ועדכון מאפיינים

get_property(name, default) קורא ערך ספציפי לתת-סוג; set_property(name, value) כותב ערך, וקביעת תכונה ל-None מסירה אותה ממילון ה-properties של ההערה.

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

מתן שם להערות עם AnnotationName

שמות PDF (למשל, ערך Name של הערת Stamp) מסומנים באופן מובחן ממחרוזות רגילות באמצעות AnnotationName, תת-מחלקה str של aspose_pdf.engine.cos. ערך שמאוחסן כך עדיין משווה למחרוזת רגילה.

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

הוספה, מחיקה וניקוי

insert(index, subtype, rect, contents, title, appearance_normal, properties) מציב הערה חדשה במיקום מסוים; delete(index) מסיר אחת לפי אינדקס (מטיל IndexError עבור אינדקס מחוץ לטווח); clear() מסיר את כל ההערות מהדף.

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

יצירת הופעות של הערות

Annotation.generate_appearance(force) בונה את זרם המראה /AP /N עבור הערה אחת ומחזיר True כאשר קיים מנגן עבור תת-הסוג הזה; AnnotationCollection.generate_appearances(force) עושה זאת עבור כל ההערות על הדף בקריאה אחת ומחזיר את מספר ההערות שנוצרו בפועל (תת-הסוגים שאינם נתמכים מדולגים).

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

תתי-סוגים ודגלים של הערות

AnnotationType מונה את שמות תתי-הסוג הסטנדרטיים של PDF 32000-1:2008 (טבלה 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, ו-REDACT.

AnnotationFlags הוא IntFlag המתאר את התנהגות הצגת/אינטראקציה של ההערה: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED, ו-TOGGLE_NO_VIEW.

גרסה קדם-שחרור: הערות 3D

PDF3DAnnotation, PDF3DArtwork, PDF3DContent ו-PDF3DView מודלים יצירת אמנות תלת-ממדית המצורפת לעמוד — PDF3DAnnotation יש rect: Rectangle, artwork: PDF3DArtwork, ו-background_color: Color אופציונלי. PDF3DArtwork.add_view() רושם PDF3DView, שכל אחד נושא render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) ו-lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM). תיאור ה-docstring של הספרייה מסמן את PDF3DAnnotation כ„מעטפת הערה מינימלית לייבוא לפני-שחרור” — יש להתייחס למשטח זה כשלב מוקדם ולא כ־API עריכת תלת-ממד מלאה.

טיפים ושיטות מומלצות

• העדף חברי enum של AnnotationType על פני מחרוזות תת-סוג גולמיות כאשר יש צורך להשוות או לבצע סינון של הערך במקומות אחרים בקוד שלך.
• הפעל את set_property(name, None) כדי להסיר נכס לחלוטין במקום להשאיר ערך מיושן במקומו — הרשומה נעלמת מ-properties באופן מוחלט.
• צור מחולל מראה במצב אצווה באמצעות AnnotationCollection.generate_appearances במקום לבצע לולאה על generate_appearance() לכל הערה; הפונקציה מחזירה את מספר הפריטים שנוצרו בפועל כך שניתן לזהות תתי-סוגים שדולפו/לא נתמכים.
• delete() והאינדקס ב-page.annotations הם שניהם מבוססי-אפס; אמת את האינדקס לפני קריאה ל-delete() אם הוא מתקבל מקלט משתמש, מכיוון שאינדקס מחוץ לטווח יגרום ל-IndexError.
• עטוף ערכי שם PDF (כמו ה-Name של Stamp) ב-AnnotationName כך שהם יעברו סיבוב חזרה כ-שמות PDF ולא כמחרוזות טקסט רגילות.

בעיות נפוצות

FAQ

איך מוסיפים הערת תגובה בטקסט רגיל?

קרא ל-page.annotations.add("Text", (x0, y0, x1, y1), "comment text"). הטופל בעל ארבעת המספרים הוא המלבן של ההערה בעמוד.

מה ההבדל בין Annotation, MarkupAnnotation ו-LinkAnnotation?

Annotation הוא תצוגה חיה המוחזרת עבור כל הערה בעמוד. MarkupAnnotation הוא הבסיס לסוגי המשנה בסגנון סימון (הדגשות, הערות טקסט, צורות) ו-LinkAnnotation נשמר עבור הערות בסגנון קישור; שניהם כיום חושפים את אותה משטח של שיטות/מאפיינים כמו Annotation.

האם אפשר להסיר מאפיין בודד מבלי למחוק את כל ההערה?

כן — קרא ל-annotation.set_property(name, None); ההערה עצמה נשארת ללא שינוי, רק אותה ערך אחד מוסר מ-properties.

האם AnnotationCollection.generate_appearances נכשל אם תת-סוג אינו נתמך?

לא. הוא מדלג על תת-סוגים ללא מנגנון הצגת מובנה ומחזיר את מספר ההערות שלגביהן נוצרה הצגה בפועל.

האם מחלקות ההערות בתלת-ממד מוכנות לייצור?

PDF3DAnnotation והסוגים הקשורים מתועדים כעטיפה מינימלית לייבוא לפני השחרור — אמת את ההתנהגות מול מציג ה-PDF היעד שלך לפני שאתה סומך עליהם לתוכן תלת-ממד בייצור.

API Reference סיכום

ראה גם

• Aspose.PDF for Python — Enterprise Documentation