איך לעבוד עם הערות PDF ב-C++

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

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

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

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

int main() {
    Aspose::Pdf::Document doc;
    std::cout << "Linked OK — pages: " << doc.Pages().Count() << "\n";
}

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/page_collection.hpp>
#include <aspose/pdf/rectangle.hpp>
#include <aspose/pdf/color.hpp>
#include <aspose/pdf/annotations/annotation.hpp>
#include <aspose/pdf/annotations/annotation_collection.hpp>
#include <aspose/pdf/annotations/annotation_type.hpp>
#include <aspose/pdf/annotations/annotation_flags.hpp>
#include <aspose/pdf/annotations/border.hpp>
#include <aspose/pdf/annotations/border_style.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>

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

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

TextAnnotation note{doc};
note.Rect(Rectangle(100.0, 700.0, 200.0, 720.0, false));
note.Contents("Reviewed and approved.");

page.Annotations().Add(note);

TextAnnotation flagged{doc};
flagged.Rect(Rectangle(100.0, 600.0, 300.0, 650.0, false));
flagged.Contents("Needs follow-up");
flagged.Color(Color::FromRgb(220, 20, 20));
flagged.Flags(AnnotationFlags::Print | AnnotationFlags::ReadOnly);
flagged.Border().Width(2);
flagged.Border().Style(BorderStyle::Dashed);

page.Annotations().Add(flagged);

doc.Save("annotated.pdf");

Document reopened("annotated.pdf");
auto& annots = reopened.Pages()[1].Annotations();

std::cout << "Annotation count: " << annots.Count() << "\n";

for (int i = 0; i < annots.Count(); ++i) {
    const auto& a = annots[i];
    if (a.AnnotationType() == AnnotationType::Text) {
        std::cout << "Text annotation: " << a.Contents() << "\n";
    }
}

annots.Delete(0);
reopened.Save("annotated-cleaned.pdf");

בעיות נפוצות ופתרונות

לא קורה שינוי ב-PDF השמור לאחר הקריאה Annotations().Add()

שתי דברים נפוצים שיכולים להשתבש כאן. ראשית, PageCollection הוא מבוסס על 1 (doc.Pages()[1] הוא הדף הראשון) בעוד AnnotationCollection הוא מבוסס על 0 (annots[0] הוא ההערה הראשונה) — בלבול בין שני סכמות האינדקס גורם לפעולה על האובייקט הלא נכון. שנית, ודא ש-Document::Save() אכן רץ לאחר שההערה מתווספת; עד אז שום דבר לא נכתב לדיסק.

AnnotationCollection אינדקסינג או Delete(index) throws std::out_of_range

אינדקסים חוקיים נעים מ-0 עד Count() - 1. העברת אינדקס שלילי או אינדקס השווה ל-Count() או גדול ממנו גורמת ל-std::out_of_range לפי תכנון. קרא ל-Count() קודם כדי להגביל כל לולאה או חיפוש.

Remove() returns false בפעם השנייה שאני קורא לו על אותה ההערה

זה אינו שגיאה. Remove() מדווח האם ההערה נמצאה והוסרה כ-bool; קריאה נוספת על הערה שכבר נעלמה היא פעולה ללא השפעה שמחזירה false. בדוק את ערך ההחזרה במקום להניח ש-Remove() תמיד מצליח.

הגדרת AnnotationFlags הערך מנקה דגלים שכבר קבעתי

Flags(value) מחליף את כל קבוצת הדגלים — הוא לא ממזג עם הערך הקודם. כדי להוסיף או למחוק דגל בודד, קרא תחילה את הדגלים הנוכחיים ושלב אותם עם אופרטורים ביטיים, לדוגמה a.Flags(a.Flags() | AnnotationFlags::Print) כדי להוסיף דגל, או a.Flags(a.Flags() & ~AnnotationFlags::Print) כדי למחוק דגל אחד תוך כדי שהשאר נשארים ללא שינוי.

שאלות נפוצות

מה הקשר בין Annotation, TextAnnotation, ולתתי-סוגי ההערה האחרים?

Annotation היא מחלקת הבסיס המשותפת. TextAnnotation ושאר סוגי ההערה הקונקרטיים ממקמים אותה לכל תת-סוג של הערת PDF, תוך שיתוף של המחלקה הבסיסית את Rect(), Contents(), Color(), Flags() ו-Border().

האם ההערות משויכות לכל המסמך או לעמוד אחד?

לכל עמוד יש את ה-AnnotationCollection שלו, המוחזר על-ידי המתודה Annotations() של אותו עמוד. ההערות תמיד משויכות לעמוד שבו הן נוספו, ולא לכל המסמך כולו.

איך אני סופר כמה הערות יש בעמוד?

קרא ל-Count() על ה-AnnotationCollection שמוחזר על-ידי Page::Annotations().

האם אפשר שההערה תהיה גם ניתנת להדפסה וגם לקריאה- בלבד בו-זמנית?

כן. AnnotationFlags הוא שדה ביטים, ולכן יש לשלב ערכים באמצעות bitwise OR, לדוגמה AnnotationFlags::Print | AnnotationFlags::ReadOnly.

האם מחיקת הערה מ-AnnotationCollection מסירה אותה מקובץ ה-PDF על הדיסק?

רק אחרי שה-Document::Save() רץ. Delete(), Remove() ו-Clear() משנים רק את האוסף בזיכרון — ה-PDF על הדיסק נשאר ללא שינוי עד שהמסמך נשמר.

ראה גם

• עבודה עם סימניות PDF (מדריך למפתחים)
• מדריך התקנה
• API Reference
• Aspose.PDF FOSS for C++ — דף מוצר
• מאגר GitHub
• Aspose.PDF for C++ — Enterprise Knowledge Base