مقدمه

حاشیه‌نویسی‌های 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 در دسترس است و می‌توان از کتابخانه در پروژه‌های تجاری و منبع باز بدون هزینه‌های لایسنس استفاده کرد.

شروع کار

منابع مرتبط