Σχόλια 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 (π.χ. η Stamp καταχώρηση Name μιας σημείωσης) σημειώνονται ξεκάθαρα από τις απλές συμβολοσειρές χρησιμοποιώντας το 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 μοντελοποιούν 3D artwork προσαρτημένο σε μια σελίδα — ένα 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 είναι ένα “ελάχιστο wrapper σχολίων για προέκδοση εισαγωγών” — θεωρήστε αυτή την επιφάνεια ως πρώιμη φάση αντί για πλήρως ανεπτυγμένο 3D authoring API.

Συμβουλές και Καλές Πρακτικές

• Προτιμήστε τα μέλη enum του AnnotationType αντί για ακατέργαστες συμβολοσειρές υποτύπου όταν η τιμή χρειάζεται επίσης να συγκριθεί ή να διακλαδωθεί σε άλλο σημείο του κώδικά σας.
• Καλέστε το set_property(name, None) για να αφαιρέσετε μια ιδιότητα εντελώς αντί να αφήσετε μια παλιά τιμή στη θέση της — η εγγραφή εξαφανίζεται εντελώς από το properties.
• Δημιουργία εμφάνισης κατά παρτίδες με το AnnotationCollection.generate_appearances αντί για επανάληψη του generate_appearance() ανά σχολίαση· επιστρέφει τον πραγματικό αριθμό που δημιουργήθηκε ώστε να μπορείτε να εντοπίσετε παραλειπόμενους/μη υποστηριζόμενους υποτύπους.
• Το delete() και η προσπέλαση του page.annotations είναι και τα δύο μηδενικής βάσης· επικυρώστε έναν δείκτη πριν καλέσετε το delete() αν προέρχεται από είσοδο χρήστη, καθώς ένας δείκτης εκτός εύρους προκαλεί το IndexError.
• Τυλίξτε τις τιμές ονομάτων PDF (όπως το Stamp’s Name) σε 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 αν ένας υποτύπος δεν υποστηρίζεται;

Όχι. Παραλείπει τους υποτύπους χωρίς ενσωματωμένο renderer εμφάνισης και επιστρέφει τον αριθμό των σημειώσεων για τις οποίες δημιουργήθηκε πραγματικά μια εμφάνιση.

Είναι οι κλάσεις σχολιασμού 3D έτοιμες για παραγωγική χρήση;

PDF3DAnnotation και οι συναφείς τύποι τεκμηριώνονται ως ελάχιστο wrapper για προ-κυκλοφορίες — επαληθεύστε τη συμπεριφορά με τον προοριζόμενο PDF viewer σας πριν βασιστείτε σε αυτά για παραγωγικό περιεχόμενο 3D.

API Reference Περίληψη

Δείτε επίσης

• Aspose.PDF for Python — Enterprise Documentation