כיצד לעבוד עם הערות PDF ב-Python

Aspose.PDF FOSS עבור Python חושף כל הערה בעמוד כאובייקט Annotation חי דרך AnnotationCollection של העמוד, כך שאתה יכול להוסיף סימון, קישור והערות תלת-ממד, לבדוק את המאפיינים הספציפיים לסוג שלהם, וליצור את זרמי המראה שמציגי PDF צריכים כדי להציג אותם — הכל מתוך Python טהור. מדריך זה מראה כיצד להתקין את הספרייה, להוסיף הערות, לקרוא אותן בחזרה, וליצור את זרמי המראה שלהן.

מדריך שלב-אחר-שלב

git clone https://github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python.git
cd Aspose-PDF-FOSS-for-Python
pip install -e .

import aspose_pdf
print("aspose_pdf OK")

from aspose_pdf import Document
from aspose_pdf.annotations import (
    Annotation,
    AnnotationType,
    AnnotationFlags,
    MarkupAnnotation,
    LinkAnnotation,
)

from aspose_pdf import Document

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

annotation = page.annotations.add(
    "Highlight",
    (100, 700, 300, 720),
    "Key clause",
)
print(type(annotation).__name__)   # MarkupAnnotation
print(annotation.contents)         # Key clause

from aspose_pdf import Document
from aspose_pdf.annotations import AnnotationType

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

annotation = page.annotations.add(
    AnnotationType.POLYGON,
    (0, 0, 10, 10),
    "",
    properties={"Vertices": [0, 0, 10, 0, 5, 10]},
)
print(annotation.subtype)                    # Polygon
print(annotation.get_property("Vertices"))   # [0, 0, 10, 0, 5, 10]

from aspose_pdf import Document

document = Document()
document.pages.add()
page = document.pages[0]
page.annotations.add("Text", (50, 50, 70, 70), "First note")
page.annotations.add("Text", (80, 80, 100, 100), "Second note")

for annotation in page.annotations:
    print(annotation.subtype, "-", annotation.contents)

from aspose_pdf import Document
from aspose_pdf.engine.cos import AnnotationName

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

stamp = page.annotations.add(
    "Stamp",
    (100, 100, 260, 150),
    "",
    properties={"Name": AnnotationName("Approved")},
)
if stamp.generate_appearance():
    print(f"Appearance stream: {len(stamp.appearance_normal)} byte(s)")

# Regenerate every missing appearance stream on the page in one call:
count = page.annotations.generate_appearances(force=True)
print(f"Regenerated {count} appearance stream(s)")

from aspose_pdf import Document
from aspose_pdf.annotations import LinkAnnotation, MarkupAnnotation

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

link = page.annotations.add("Link", (50, 750, 200, 770), "")
highlight = page.annotations.add("Highlight", (50, 700, 200, 720), "")

print(isinstance(link, LinkAnnotation))         # True
print(isinstance(highlight, MarkupAnnotation))  # True

בעיות נפוצות ותיקונים

get_property returns None למאפיין שהגדרתי זה עתה

properties מפתחות הם שמות שדות PDF מדויקים, רגישים לאותיות ("Vertices", "Name" וכדומה) — שגיאת כתיב או רישיות שגויה מתעלמים בשקט במקום לזרוק שגיאה. העבר ארגומנט default ל-get_property(name, default) ובדוק אותו במפורש בזמן ניפוי תת-סוג חדש.

generate_appearance() returns False

לא כל שילוב של תת-סוג ותכונה ניתן להמחזה ל-appearance stream על-ידי היוצר המובנה. יש לבדוק את has_appearance לפני שמניחים שהקריאה הצליחה, ולספק appearance_normal מוקדם (bytes) ישירות על add() עבור תת-סוגים שהיוצר אינו מכסה.

תת-מחלקת אנוטציה בלתי צפויה אחרי add()

המחרוזת של תת-הסוג (או החבר AnnotationType) שאתה מעביר מגדירה את המחלקה המוחזרת: תתי-סוגי markup חוזרים כ-MarkupAnnotation, "Link" חוזר כ-LinkAnnotation, וכל תת-סוג מוכר אחר חוזר כ-Annotation הבסיסי. השתמש ב-isinstance() נגד MarkupAnnotation/LinkAnnotation במקום להניח מחרוזת תת-סוג ספציפית.

AnnotationFlags הערכים אינם נראים משנים את הרינדור

AnnotationFlags (PRINT, HIDDEN, NO_ZOOM, READ_ONLY, ו-דומיו) הוא enum סטנדרטי של Python IntFlag ליצירת ופירוש ביטי ההתנהגות של annotation בעזרת האופרטור | — הוא סוג ערך, ולא מאפיין ש-Annotation.add() כותב אוטומטית. שלב את הדגלים שאתה צריך והעבר אותם דרך מנגנון properties הספציפי לסוג המשמש לנתונים ספציפיים לתת-סוג אחרים.

עבודה עם דף שאין לו עדיין anotations

page.annotations הוא תמיד AnnotationCollection תקף (אולי ריק) — אין צורך אף פעם לבדוק עבור None לפני קריאה ל-add(), איטרציה, או קריאה ל-clear().

שאלות נפוצות

אילו תתי-סוגי סימון Aspose.PDF FOSS עבור Python נתמכים?

AnnotationType מונה את כל 25 תתי-הסוגים הסטנדרטיים של PDF 32000-1:2008 בטבלה 169, כולל TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, HIGHLIGHT, STAMP, INK, FILE_ATTACHMENT, REDACT, ועוד.

האם ספרייה זו תומכת בסימונים תלת-ממדיים?

כן. PDF3DAnnotation, יחד עם PDF3DArtwork, PDF3DContent, PDF3DView, PDF3DLightingScheme, וגם PDF3DRenderMode, מדגם משטח אנוטציה מינימלי של PDF 3D (מרובע, גרפיקה משובצת, ותצוגות בשם) עבור זרימות עבודה של PDF 3D לפני השחרור. ראה את הפניה ל-PDF3DAnnotation למערך המלא של המאפיינים שלו.

איך להסיר סימון מדף?

הקרא ל-page.annotations.delete(index) כדי להסיר סימון אחד לפי מיקום, או ל-page.annotations.clear() כדי להסיר את כל הסימונים בדף.

האם אפשר להכניס סימון במיקום ספציפי במקום לצרפו?

כן — AnnotationCollection.insert(index, subtype, rect, contents, title, appearance_normal, properties) מקבל את אותם הארגומנטים כמו add() בתוספת המטרה index.

איך הצבע של ההערה מיוצג?

המאפיין color ב-Annotation (ובתתי-המחלקה שלו) הוא tuple[float, ...] התואם למספר הרכיבים של ערך ה-PDF /C (ריק כאשר הצבע אינו מוגדר) — ולא אובייקט צבע ייעודי.

ראה גם

• ניהול מסמכים (מדריך למפתח)
• כיצד לטעון מסמך ב-Python
• מדריך התקנה
• API Reference
• מאגר GitHub
• Aspose.PDF for Python — Enterprise Knowledge Base