مقدمة

تغطي تعليقات 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() يحدد أي نوع فرعي ملموس يمثل كل إدخال. هذا يسمح للرمز المستدعي بالتفرع بناءً على قيمة التعداد دون الحاجة لمعرفة مسبقة أي أنواع التعليقات التوضيحية يحتويها ملف 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، ويمكن استخدام المكتبة في المشاريع التجارية ومفتوحة المصدر دون رسوم ترخيص.

البدء

الموارد ذات الصلة