מבוא

ההערות ב-PDF מכסות מגוון רחב של אלמנטים אינטראקטיביים ויזואליים המונחים מעל תוכן העמוד: פתקים טקסטיים דביקים, קישורים, טקסט מודגש או מחוק, צורות גאומטריות, קווי דיו, קבצים מצורפים, וחותמות אישור. Aspose.PDF FOSS עבור C++ מייצג כל אחד מאלו כתת-מחלקה קונקרטית של Annotation, כך שקוד שמטייל בהערות של עמוד יכול לעבוד באופן כללי נגד המחלקה הבסיסית ועדיין להגיע לחברי תת-סוג ספציפיים — כגון Icon() ב-TextAnnotation או Action() ב-LinkAnnotation — כאשר נדרש.

ה-enum Annotations::AnnotationType של הספרייה מונה את תתי-הסוגים שהיא מזהה: Text, Link, FreeText, Line, Square, Circle, Polygon, PolyLine, Highlight, Underline, Squiggly, StrikeOut, Stamp, Caret, Ink, Popup, FileAttachment, Sound, Movie, Widget, Screen, PrinterMark, Watermark, Redaction, RichMedia, ועוד כמה. כל ערך ממופה למחלקה קונקרטית — CircleAnnotation, SquareAnnotation, PolygonAnnotation, PolylineAnnotation, ו-LineAnnotation עבור סימון צורות; FreeTextAnnotation ו-InkAnnotation עבור טקסט חופשי וקווי ציור; FileAttachmentAnnotation, SoundAnnotation, MovieAnnotation, ScreenAnnotation, ו-RichMediaAnnotation עבור תוכן משובץ; ו-WidgetAnnotation עבור מראה שדות AcroForm.

פוסט זה מכסה את API הבסיסיים Annotation ו-AnnotationCollection, כולל הוספת פתקים טקסטיים וקישורים, זיהוי סוגי ההערות בעת טעינת מסמך קיים, וקריאה או עדכון של מטא-נתוני סימון וחותמות. Aspose.PDF FOSS עבור C++ היא ספריית C++20 ללא תלות בזמן ריצה מעבר לספרייה הסטנדרטית; קבצי הכותרת נכללים ישירות מתיקיית aspose/pdf/annotations/ והספרייה נבנית כיעד CMake.

מה כלול

Annotation ו-AnnotationCollection

Annotation היא המחלקה הבסיסית לכל תת-סוג של הערה. היא חושפת מאפיינים משותפים: Rect() / Rect(value) למלבן הגבול של ההערה, Contents() לטקסט המשויך, Name(), Color(), Flags() (מסכת סיביות של AnnotationFlags — Print, Hidden, Invisible, NoZoom, ReadOnly, ואחרים), Border(), Width() / Height(), AnnotationType(), ו-PageIndex(). AnnotationCollection מחזיקה את ההערות בעמוד יחיד ונגישה דרך Page.Annotations().

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/annotation_collection.hpp>
#include <iostream>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("reviewed.pdf");
AnnotationCollection& annots = doc.Pages()[1].Annotations();

std::cout << "Annotation count: " << annots.Count() << "\n";
for (int i = 0; i < annots.Count(); ++i) {
    Annotation& a = annots[i];
    std::cout << "  " << a.Name() << ": " << a.Contents() << "\n";
}

AnnotationCollection גם חושפת את Add(annotation), Add(annotation, considerRotation), Delete(index), Delete(annotation), Clear(), Remove(annotation), Contains(annotation), ו-IsReadOnly().

הערות טקסט עם TextAnnotation

TextAnnotation מייצגת את ההערה מוכרת של פתק דביק. מעבר לחברי הבסיס של Annotation, היא מוסיפה Open() / Open(value) לשליטה האם הפתק מוצג מורחב, ו-Icon() / Icon(value) (ערך TextIcon כגון Note, Comment, Key, Help, או Check) לבחירת סמל האייקון.

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("input.pdf");

TextAnnotation note{doc};
note.Rect(Rectangle{100.0, 700.0, 200.0, 720.0, false});
note.Contents("Reviewed by QA");
note.Icon(TextIcon::Comment);
note.Open(true);

doc.Pages()[1].Annotations().Add(note);
doc.Save("annotated.pdf");

קישורים ופעולות עם LinkAnnotation

LinkAnnotation מצרף אזור לחיצה לדף. הוא נבנה מה-Page הבעלים ו-Rectangle, וההתנהגות שלו נקבעת עם Action(value) — כל תת-מחלקה של PdfAction, כולל NamedAction (ניווט מוגדר מראש כגון PredefinedAction::LastPage), GoToAction, GoToURIAction או JavascriptAction. Destination() קוראת את יעד ה-IAppointment של הקישור, ו-Highlighting() / Highlighting(value) מגדירים את HighlightingMode (None, Invert, Outline, Push, Toggle) המיושם כאשר הקישור מופעל.

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/link_annotation.hpp>
#include <aspose/pdf/annotations/named_action.hpp>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc;
Page page = doc.Pages().Add();

LinkAnnotation link{page, Rectangle{0.0, 0.0, 100.0, 20.0, false}};
link.Action(NamedAction{PredefinedAction::LastPage});
link.Highlighting(HighlightingMode::Push);

page.Annotations().Add(link);

זיהוי סוגי ההסברים בעת הטעינה

כאשר מסמך נפתח, ההערות הקיימות כבר ממולאות ב-AnnotationCollection של כל דף, ו-AnnotationType() מזהה איזו תת-מחלקה קונקרטית כל ערך מייצג. זה מאפשר לקוד הקורא לסווג לפי ערך ה-enum מבלי לדעת מראש אילו סוגי הערות מכיל קובץ PDF מסוים.

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/annotation_type.hpp>
#include <iostream>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("mixed-annotations.pdf");
auto& annots = doc.Pages()[1].Annotations();

for (int i = 0; i < annots.Count(); ++i) {
    switch (annots[i].AnnotationType()) {
        case AnnotationType::Text:      std::cout << "Text note\n"; break;
        case AnnotationType::Link:      std::cout << "Link\n"; break;
        case AnnotationType::Circle:    std::cout << "Circle shape\n"; break;
        case AnnotationType::Square:    std::cout << "Square shape\n"; break;
        case AnnotationType::Highlight: std::cout << "Highlight\n"; break;
        case AnnotationType::Stamp:     std::cout << "Stamp\n"; break;
        default: break;
    }
}

מטא-נתונים של סימון ההסבר

MarkupAnnotation הוא הבסיס להערות שנושאות מטא-נתוני מבקר: Title() (המחבר), Subject(), RichText() לטקסט תגובה מעוצב, ו-Opacity() למיזוג עם תוכן הדף. InReplyTo() ו-Popup() מחברים הערת סימון לשרשור ההערות שאליו היא שייכת, ו-ClearState() / SetReviewState(state, userName) מנהלים את מצב הסקירה שלה. HighlightAnnotation, UnderlineAnnotation, StrikeOutAnnotation ו-SquigglyAnnotation הן תתי-סוגים של סימון הממוקמים מעל טקסט; הבסיס המשותף שלהם TextMarkupAnnotation מוסיף QuadPoints() להגדרת האזורים המרובעים המכוסים ו-GetMarkedText() לקריאת הטקסט שמתחת.

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/markup_annotation.hpp>

using namespace Aspose::Pdf::Annotations;

for (int i = 0; i < annots.Count(); ++i) {
    if (auto* markup = dynamic_cast<MarkupAnnotation*>(&annots[i])) {
        markup->Title("QA Reviewer");
        markup->Subject("Layout issue");
        markup->Opacity(0.6);
    }
}

הערות חותמת עם StampAnnotation

StampAnnotation מציב חותמת מוגדרת מראש או מותאמת אישית על דף. Icon() / Icon(value) בוחר ערך StampIcon — Approved, Draft, Confidential, Final, Expired, NotApproved, ForComment, TopSecret ואחרים — ו-Image() / Image(value) מספקים בתים גולמיים של תמונה למראה חותמת מותאמת במקום סמל מובנה.

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/stamp_annotation.hpp>

using namespace Aspose::Pdf::Annotations;

for (int i = 0; i < annots.Count(); ++i) {
    if (auto* stamp = dynamic_cast<StampAnnotation*>(&annots[i])) {
        stamp->Icon(StampIcon::Approved);
    }
}

התחלה מהירה

הוסיפו את הספרייה כתת-תיקייה של CMake וקשרו אל יעד aspose_pdf_foss:

add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

פתחו מסמך, הוסיפו פתק טקסט וקראו את מספר ההערות חזרה:

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>
#include <iostream>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

int main() {
    Document doc("input.pdf");

    TextAnnotation note{doc};
    note.Rect(Rectangle{100.0, 700.0, 200.0, 720.0, false});
    note.Contents("Reviewed by QA");
    note.Icon(TextIcon::Comment);

    doc.Pages()[1].Annotations().Add(note);
    doc.Save("annotated.pdf");

    std::cout << "Annotations on page 1: "
              << doc.Pages()[1].Annotations().Count() << "\n";
}

פורמטים נתמכים

פורמטהרחבהקריאהכתוב
BMP.bmp—✓
JPEG.jpg—✓
TIFF.tiff—✓
Text.txt—✓
SVG.svg✓—

תמיכת הפורמט חלה על רינדור דפים ואפשרויות טעינה ברמת המסמך; רשומות אלו משקפות נתיבי ייצוא מאומתים (BmpDevice, JpegDevice, TiffDevice, TextDevice) וייבוא (SvgLoadOptions) במקום סריאליזציה ספציפית להערות.

קוד פתוח ורישוי

Aspose.PDF FOSS עבור C++ משוחרר תחת רישיון MIT. קוד המקור זמין בכתובת https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp, והספרייה ניתנת לשימוש בפרויקטים מסחריים וקוד פתוח ללא תשלומי רישיון.

התחלה

משאבים קשורים