کار با حاشیه‌نویسی‌های 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 داده‌های فرم را از طریق یک FileSpecification به یک URL ارسال می‌کند:

#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() علاوه بر این یک خط‌کشی 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 باز می‌گرداند.
• قبل از تبدیل یا انشعاب بر رفتار زیرنوع، هنگام پیمایش حاشیه‌نویسی‌های بارگذاری‌شده از یک فایل PDF غیرقابل اعتماد یا شخص ثالث، Annotation.AnnotationType() را بررسی کنید.
• قبل از بایگانی یک سند، حاشیه‌نویسی‌ها را با Annotation.Flatten() (یا PdfAnnotationEditor.FlatteningAnnotations() برای کل سند) مسطح کنید تا مرورگران در ابزارهای دیگر همان ظاهر را که شما ایجاد کرده‌اید ببینند.
• AnnotationFlags یک بیت‌فیلد است — پرچم‌ها را با مقادیر عددی پایه‌ی enum ترکیب کنید به جای این‌که فرض کنید تنها یک پرچم می‌تواند همزمان فعال باشد.

مسائل رایج

FAQ

چگونه می‌توانم یک حاشیه‌نویسی به سبک کامنت را به یک صفحه PDF اضافه کنم؟

یک TextAnnotation با هدف Document بسازید، Rect() و Contents() آن را تنظیم کنید، سپس قبل از ذخیره‌سازی، آن را به page.Annotations() اضافه کنید.

چگونه بفهمم به چه نوع annotation‌ای نگاه می‌کنم؟

متد Annotation.AnnotationType() را فراخوانی کنید که یک مقدار enum AnnotationType برمی‌گرداند، مانند Text، Link، Highlight، FreeText، FileAttachment یا Watermark.

آیا یک annotation می‌تواند بیش از یک flag داشته باشد؟

بله. AnnotationFlags یک bitfield است (Default، Invisible، Hidden، Print، NoZoom، ReadOnly، LockedContents و …)، بنابراین می‌توان چندین flag را در یک annotation ترکیب کرد.

تفاوت بین flatten کردن یک annotation و flatten کردن یک سند چیست؟

Annotation.Flatten() یک annotation واحد را به محتوای صفحهٔ آن ادغام می‌کند. PdfAnnotationEditor.FlatteningAnnotations() (به‌صورت اختیاری توسط بازهٔ صفحات و AnnotationType از طریق overload که start، end و annotType را می‌پذیرد) کل سند باند شده را در یک فراخوانی flatten می‌کند.

چگونه تمام annotationهای یک نوع را از یک سند حذف کنم؟

سند را با PdfAnnotationEditor.BindPdf() bind کنید، DeleteAnnotations(annotType) را با AnnotationType هدف فراخوانی کنید، سپس نتیجه را Save() کنید.

API Reference خلاصه

همچنین ببینید:

• Aspose.PDF — Enterprise Documentation