עבודה עם הערות PDF

עבודה עם הערות PDF

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

הוספת הערות לדף

צור מופע הערה קונקרטי, מיקום אותו באמצעות Rectangle, והוסף אותו לאוסף של הדף בעזרת AnnotationCollection.Add(). TextAnnotation מייצג תגובה בסגנון פתק דביק שמוצמד לנקודה על הדף:

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

int main() {
    Aspose::Pdf::Document doc("input.pdf");
    auto& page = doc.Pages()[1];

    Aspose::Pdf::Annotations::TextAnnotation note(doc);
    note.Rect(Aspose::Pdf::Rectangle(100.0, 700.0, 200.0, 720.0, false));
    note.Contents("Reviewed and approved");

    page.Annotations().Add(note);
    doc.Save("annotated.pdf");
}

Annotation.Contents() / Contents(value) מקבלים וקובעים את טקסט ההערה, ו-Annotation.Rect() / Rect(value) ממקמים את ההערה על הדף.

חזרה והסרת הערות

AnnotationCollection תומך בספירה, גישה לפי אינדקס, בדיקות חברות והסרה לפי ערך או לפי אינדקס:

#include <aspose/pdf/document.hpp>

int main() {
    Aspose::Pdf::Document doc("input.pdf");
    auto& annotations = doc.Pages()[1].Annotations();

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

    for (int i = 0; i < annotations.Count(); ++i) {
        std::cout << "Contents: " << annotations[i].Contents() << "\n";
    }

    if (annotations.Count() > 0) {
        annotations.Delete(0);   // remove by index
    }
    annotations.Clear();         // remove everything
}

AnnotationCollection.Contains(annotation) ו-Remove(annotation) פועלים על הפנייה ספציפית להערה; Delete(index) מסיר לפי מיקום, ו-Delete(annotation) מסיר הערה ספציפית ללא צורך במיקומה. IsReadOnly() מדווח האם ניתן לשנות את האוסף.

קריאת הערות ממסמך קיים

כאשר מסמך נטען, ההערות שלו כבר ממולאו וניתן לבדוק אותן ללא הוספת משהו. Annotation.AnnotationType() מדווח על תת-סוג (AnnotationType::Text, AnnotationType::Highlight, AnnotationType::Link, AnnotationType::FreeText, AnnotationType::FileAttachment, AnnotationType::Watermark ואחרים):

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

int main() {
    Aspose::Pdf::Document doc("annotated.pdf");
    auto& annotations = doc.Pages()[1].Annotations();

    for (int i = 0; i < annotations.Count(); ++i) {
        auto& a = annotations[i];
        if (a.AnnotationType() == Aspose::Pdf::Annotations::AnnotationType::Text) {
            std::cout << "Note: " << a.Contents() << "\n";
        }
    }
}

סדר ההערות ותת-הסוג נשמרים במהלך שמירה/טעינה חוזרת, ולכן קוד המתייחס ל-Annotations() לאחר טעינת מסמך רואה את אותה סדרה שהייתה נוכחת כאשר הקובץ נכתב.

הערות קישור ופעולות

LinkAnnotation מצרף אזור לחיץ לעמוד ומשגר PdfAction בעת הפעלה. NamedAction מקפץ ליעד ניווט מוגדר מראש, JavascriptAction מריץ מחרוזת ECMAScript, ו-SubmitFormAction שולח נתוני טופס ל-URL דרך FileSpecification:

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

int main() {
    Aspose::Pdf::Document doc;
    auto page = doc.Pages().Add();

    Aspose::Pdf::Annotations::LinkAnnotation link(
        page, Aspose::Pdf::Rectangle(0.0, 0.0, 100.0, 20.0, false));
    link.Action(Aspose::Pdf::Annotations::NamedAction(
        Aspose::Pdf::Annotations::PredefinedAction::LastPage));

    page.Annotations().Add(link);
    doc.Save("linked.pdf");
}

LinkAnnotation.Action(value) מקבל כל תת-סוג של PdfAction ומשכפל אותו פנימית, כך שההערה שומרת על עותק משלה של הפעולה. LinkAnnotation.Destination() / Destination(value) מגדירים יעד ניווט מפורש במקום פעולה, ו-Highlighting() / Highlighting(value) שולטים במשוב הוויזואלי המוצג בזמן הקלקת הקישור.

מראה ההערה: גבול, דגלים וצבע

כל Annotation מציג Border, שדה ביט של AnnotationFlags, ו-Color המשמש להצגת המראה שלו:

#include <aspose/pdf/annotations/border_style.hpp>
#include <aspose/pdf/annotations/annotation_flags.hpp>
#include <aspose/pdf/color.hpp>

// 'note' is an existing Annotation reference, e.g. from AnnotationCollection.
note.Border().Width(2);
note.Border().Style(Aspose::Pdf::Annotations::BorderStyle::Dashed);
note.Flags(Aspose::Pdf::Annotations::AnnotationFlags::Print);
note.Color(Aspose::Pdf::Color::Red());

Border.Style() מקבל BorderStyle::Solid, Dashed, Beveled, Inset או Underline. בנוסף, Border.Effect() תומך ב-outline BorderEffect::Cloudy עם EffectIntensity() ששולט כמה הוא בולט. AnnotationFlags הוא שדה ביט — יש לשלב ערכים כגון Print, NoZoom, ReadOnly ו-LockedContents כדי לשלוט איך ההערה מתנהגת במציג מבלי לשנות את התוכן הגלוי שלה.

השטחת הערות

הערה בודדת יכולה להיות משטחת — משולבת בתוכן העמוד והופכת ללא אינטראקטיבית — על-ידי קריאה ישירה ל-Annotation.Flatten():

#include <aspose/pdf/document.hpp>

int main() {
    Aspose::Pdf::Document doc("annotated.pdf");
    auto& annotations = doc.Pages()[1].Annotations();
    for (int i = 0; i < annotations.Count(); ++i) {
        annotations[i].Flatten();
    }
    doc.Save("flattened.pdf");
}

לפעולות הערה ברמת המסמך כולו, PdfAnnotationEditor פועל לפי תבנית Facade המשותפת המשמשת ב-API: קיבוע מסמך מקור עם BindPdf(), יישום פעולה או יותר של הערות, ואז כתיבת התוצאה עם Save():

#include <aspose/pdf/facades/pdf_annotation_editor.hpp>

int main() {
    Aspose::Pdf::Facades::PdfAnnotationEditor editor;
    editor.BindPdf("annotated.pdf");
    editor.FlatteningAnnotations();
    editor.Save("flattened.pdf");
}

PdfAnnotationEditor.DeleteAnnotations() מסיר כל הערה מהמסמך הקשור; DeleteAnnotations(annotType) מגביל את ההסרה להערה אחת AnnotationType. ImportAnnotationsFromXfdf(xfdfFile) ו-ImportAnnotationsFromFdf(fdfFile) טוענים נתוני הערה שיוצאו ממציג PDF אחר.

טיפים ושיטות עבודה מומלצות

• תמיד יש להוסיף הערה שנבנתה זה עתה ל-Page.Annotations() לפני קריאה ל-Document.Save() — הערה שמעולם לא מתווספת לאוסף אינה נכתבת לקובץ הפלט.
• השתמש בAnnotationCollection.Contains(annotation) לפני קריאה לRemove() אם אינך בטוח שההערה עדיין קיימת; Remove() מחזירה false במקום לזרוק שגיאה כאשר ההערה חסרה.
• בדוק את Annotation.AnnotationType() לפני המרה או בחירה בהתנהגות תת-הסוג כאשר עוברים על ההערות שנטענו מקובץ PDF לא מהימן או ממקור צד שלישי.
• שטח את ההערות עם Annotation.Flatten() (או PdfAnnotationEditor.FlatteningAnnotations() לכל המסמך) לפני אריזת מסמך כך שסוקרים בכלים אחרים יראו את אותו המראה שיצרת.
• AnnotationFlags הוא שדה ביטים — שלב דגלים עם ערכי המספר השלם הבסיסיים של האנומייה במקום להניח שרק דגל אחד יכול להיות פעיל בו זמנית.

בעיות נפוצות

FAQ

איך מוסיפים הערת סגנון תגובה לדף PDF?

צור TextAnnotation עם היעד Document, הגדר את Rect() ו-Contents(), ואז הוסף אותו ל-page.Annotations() לפני השמירה.

איך אני יודע איזה סוג של סימון אני רואה?

קרא ל-Annotation.AnnotationType(), שמחזיר ערך enum מסוג AnnotationType כגון Text, Link, Highlight, FreeText, FileAttachment או Watermark.

האם סימון אחד יכול לשאת יותר מדגל אחד?

כן. AnnotationFlags הוא שדה ביטים (Default, Invisible, Hidden, Print, NoZoom, ReadOnly, LockedContents ואחרים), ולכן ניתן לשלב מספר דגלים על סימון אחד.

מה ההבדל בין שיטוח של סימון אחד לשיטוח של מסמך?

Annotation.Flatten() ממזג סימון יחיד לתוך תוכן העמוד שלו. PdfAnnotationEditor.FlatteningAnnotations() (אופציונלית מוגבל לפי טווח דפים ו-AnnotationType דרך ה-overload שמקבל start, end ו-annotType) משיטח את כל המסמך המקושר בקריאה אחת.

איך אני מסיר את כל הסימונים מסוג מסוים ממסמך?

קשר את המסמך עם PdfAnnotationEditor.BindPdf(), קרא ל-DeleteAnnotations(annotType) עם ה-AnnotationType הרצוי, ואז Save() את התוצאה.

API Reference סיכום

ראה גם

• Aspose.PDF — Enterprise Documentation