Πώς να εργαστείτε με τις σημειώσεις PDF στο Python

Aspose.PDF FOSS για Python εκθέτει κάθε σημείωση σε μια σελίδα ως ένα ζωντανό αντικείμενο Annotation μέσω του AnnotationCollection της σελίδας, ώστε να μπορείτε να προσθέτετε σήμανση, συνδέσμους και 3D σημειώσεις, να εξετάζετε τις ιδιότητες ειδικές για κάθε τύπο, και να δημιουργείτε τα streams εμφάνισης που χρειάζονται οι προβολείς PDF για να τα αποτυπώσουν — όλα από καθαρό Python. Αυτός ο οδηγός δείχνει πώς να εγκαταστήσετε τη βιβλιοθήκη, να προσθέσετε σημειώσεις, να τις διαβάσετε ξανά και να δημιουργήσετε τα streams εμφάνισης.

Οδηγός βήμα-βήμα

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

Δεν μπορεί κάθε συνδυασμός υποτύπου και ιδιότητας να συντεθεί σε ροή εμφάνισης από τον ενσωματωμένο γεννήτρια. Ελέγξτε το has_appearance πριν υποθέσετε ότι η κλήση πέτυχε, και παρέχετε ένα προ-αποτυπωμένο appearance_normal (bytes) απευθείας στο add() για υποτύπους που δεν καλύπτονται από τη γεννήτρια.

Απρόσμενη υποκατηγορία annotation μετά add()

Η συμβολοσειρά υποτύπου (ή το μέλος AnnotationType) που περνάτε καθορίζει την επιστρεφόμενη κλάση: οι υποτύποι σήμανσης επιστρέφουν ως MarkupAnnotation, το "Link" επιστρέφει ως LinkAnnotation, και οποιοσδήποτε άλλος αναγνωρισμένος υποτύπος επιστρέφει ως η βασική Annotation. Χρησιμοποιήστε το isinstance() εναντίον MarkupAnnotation/LinkAnnotation αντί να υποθέτετε συγκεκριμένη συμβολοσειρά υποτύπου.

AnnotationFlags τιμές δεν φαίνεται να αλλάζουν την απόδοση

AnnotationFlags (PRINT, HIDDEN, NO_ZOOM, READ_ONLY, και παρόμοια) είναι μια τυπική Python IntFlag enum για τη σύνθεση και ερμηνεία των bit συμπεριφοράς ενός σχολιασμού με τον τελεστή | — είναι τύπος τιμής, όχι ιδιότητα που το Annotation.add() γράφει αυτόματα. Συνδυάστε τις σημαδοφόρους που χρειάζεστε και περάστε τις μέσω του ίδιου τύπου-συγκεκριμένου μηχανισμού properties που χρησιμοποιείται για άλλα δεδομένα ειδικά για υποτύπους.

Εργασία με μια σελίδα που δεν έχει ακόμη σχολιασμούς

page.annotations είναι πάντα ένα έγκυρο (πιθανώς κενό) AnnotationCollection — δεν χρειάζεται ποτέ να ελέγξετε για None πριν καλέσετε το add(), επαναλάβετε, ή καλέσετε το clear().

Συχνές Ερωτήσεις

Ποιοι υποτύποι annotation υποστηρίζει το 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 και άλλων.

Υποστηρίζει αυτή η βιβλιοθήκη τα 3D annotations;

Ναι. PDF3DAnnotation, μαζί με PDF3DArtwork, PDF3DContent, PDF3DView, PDF3DLightingScheme, και PDF3DRenderMode, μοντελοποιεί μια ελάχιστη επιφάνεια annotation PDF 3D (ένα rectangle, embedded artwork, και named views) για prerelease PDF 3D workflows. Δείτε το αναφορά PDF3DAnnotation για το πλήρες σύνολο ιδιοτήτων του.

Πώς αφαιρώ ένα annotation από μια σελίδα;

Καλέστε το page.annotations.delete(index) για να αφαιρέσετε ένα annotation με βάση τη θέση, ή το page.annotations.clear() για να αφαιρέσετε όλα τα annotations στη σελίδα.

Μπορώ να εισάγω ένα annotation σε συγκεκριμένη θέση αντί να το προσθέσω στο τέλος;

Ναι — 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