Làm việc với chú thích PDF

Lấm việc với chú thích PDF

Các chú thích PDF trong Aspose.PDF FOSS cho C++ được biểu diễn bởi lớp cộn Annotation và các loại con cụ thể của nó (TextAnnotation, LinkAnnotation, HighlightAnnotation, FreeTextAnnotation, CircleAnnotation, WatermarkAnnotation, WidgetAnnotation, và các loại khác). Mỗi trang cung cấp các chú thích của mình thông qua Page.Annotations(), trả về một AnnotationCollection. Hướng dẫn này bao gồm việc thêm chú thích vào một trang, duyệt và xóa chúng, đọc chú thích từ tài liệu hiện có, gắn các hành động liên kết, tùy chỉnh giao diện và lập phẳng các chú thích.

Thêm chú thích vào một trang

Tạo một thể hiện chú thích cụ thể, đặt vị trí cho nó bằng Rectangle, và thêm nó vào bộ sưu tập của trang bằng AnnotationCollection.Add(). TextAnnotation đại diện cho một bình luận kiểu ghi chú dán được neo vào một điểm trên trang:

#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) lấy và đặt văn bản ghi chú, và Annotation.Rect() / Rect(value) định vị chú thích trên trang.

Duyệt và Xoá chú thích

AnnotationCollection hỗ trợ đếm, truy cập theo chỉ mục, kiểm tra thành viện, và xóa thêm giá trị hoặc thêm chỉ mục:

#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) và Remove(annotation) hoạt động trên một tham chiếu chú thích cụ thể; Delete(index) xóa theo vị trí, và Delete(annotation) xóa một chú thích cụ thể mà không cần chỉ mục của nó. IsReadOnly() báo cáo liệu bộ sưu tập có thể được sửa đổi hay không.

Đọc các chú thích từ tài liệu hiện có

Khi tài liệu được tải, các chú thích của nó đã được điền sẵn và có thể được kiểm tra mà không cần thêm bất kỳ thứ gì. Annotation.AnnotationType() báo cáo kiểu phụ (AnnotationType::Text, AnnotationType::Highlight, AnnotationType::Link, AnnotationType::FreeText, AnnotationType::FileAttachment, AnnotationType::Watermark, và các loại khác):

#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";
        }
    }
}

Thứ tự và kiểu phụ của chú thích được giữ nguyên qua quá trình lưu/tải lại, vì vậy mã truy cập Annotations() sau khi tải tài liệu sẽ thấy cùng một chuỗi như khi tệp được ghi.

Chú thích Liên kết và Hành động

LinkAnnotation gắn một vùng có thể nhấp vào vào trang và phát sinh một PdfAction khi được kích hoạt. NamedAction chuyển tới một mục tiêu điều hướng đã định sẵn, JavascriptAction chạy một chuỗi ECMAScript, và SubmitFormAction gửi dữ liệu biểu mẫu tới một URL thông qua một 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) chấp nhận bất kỳ kiểu phụ PdfAction nào và sao chép nó nội bộ, vì vậy chú thích giữ lại bản sao riêng của hành động. LinkAnnotation.Destination() / Destination(value) thiết lập một mục tiêu điều hướng rõ ràng thay vì một hành động, và Highlighting() / Highlighting(value) kiểm soát phản hồi hình ảnh được hiển thị khi liên kết được nhấp.

Diện mạo Chú thích: Viền, Cờ và Màu sắc

Mỗi Annotation tiết lộ một Border, một trường bit của AnnotationFlags, và một Color dùng để hiển thị giao diện của nó:

#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() chấp nhận BorderStyle::Solid, Dashed, Beveled, Inset, hoặc Underline. Border.Effect() còn hỗ trợ một đường viền BorderEffect::Cloudy với EffectIntensity() điều khiển mức độ nổi bật của nó. AnnotationFlags là một trường bit — kết hợp các giá trị như Print, NoZoom, ReadOnly, và LockedContents để kiểm soát cách một chú thích hoạt động trong trình xem mà không thay đổi nội dung hiển thị.

Làm phẳng chú thích

Một chú thích duy nhất có thể được làm phẳng — hợp nhất vào nội dung trang và trở nên không tương tác — bằng cách gọi trực tiếp 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");
}

Đối với các thao tác chú thích trên toàn bộ tài liệu, PdfAnnotationEditor tuân theo mẫu Facade chung được sử dụng trên API: gắn một tài liệu nguồn bằng BindPdf(), áp dụng một hoặc nhiều thao tác chú thích, sau đó ghi kết quả bằng 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() xóa mọi chú thích khỏi tài liệu đã gắn; DeleteAnnotations(annotType) giới hạn việc xóa chỉ một AnnotationType duy nhất. ImportAnnotationsFromXfdf(xfdfFile) và ImportAnnotationsFromFdf(fdfFile) tải dữ liệu chú thích được xuất từ một trình xem PDF khác.

Mẹo và Thực hành tốt nhất

• Luôn thêm một chú thích mới được tạo vào Page.Annotations() trước khi gọi Document.Save() — một chú thích không bao giờ được thêm vào bộ sưu tập sẽ không được ghi vào tệp đầu ra.
• Sử dụng AnnotationCollection.Contains(annotation) trước khi gọi Remove() nếu bạn không chắc annotation vẫn còn; Remove() trả về false thay vì ném lỗi khi annotation không tồn tại.
• Kiểm tra Annotation.AnnotationType() trước khi chuyển đổi kiểu hoặc nhánh dựa trên hành vi subtype khi duyệt qua các annotation được tải từ tệp PDF không đáng tin cậy hoặc của bên thứ ba.
• Làm phẳng các annotation bằng Annotation.Flatten() (hoặc PdfAnnotationEditor.FlatteningAnnotations() cho toàn bộ tài liệu) trước khi lưu trữ tài liệu để những người xem trên các công cụ khác thấy cùng một giao diện mà bạn đã tạo.
• AnnotationFlags là một bitfield — kết hợp các cờ với các giá trị nguyên cơ bản của enum thay vì giả định chỉ có một cờ có thể hoạt động cùng một lúc.

Các vấn đề phổ biến

FAQ

Làm sao để thêm annotation dạng bình luận vào một trang PDF?

Tạo một TextAnnotation với Document mục tiêu, đặt Rect() và Contents() của nó, sau đó thêm nó vào page.Annotations() trước khi lưu.

Làm sao tôi có thể biết tôi đang xem loại chú thích nào?

Gọi Annotation.AnnotationType(), hàm này trả về một giá trị enum AnnotationType như Text, Link, Highlight, FreeText, FileAttachment, hoặc Watermark.

Một chú thích có thể mang hơn một cờ không?

Có. AnnotationFlags là một bitfield (Default, Invisible, Hidden, Print, NoZoom, ReadOnly, LockedContents, và các giá trị khác), vì vậy nhiều cờ có thể được kết hợp trên một chú thích duy nhất.

Sự khác nhau giữa việc làm phẳng một chú thích và làm phẳng một tài liệu là gì?

Annotation.Flatten() hợp nhất một chú thích duy nhất vào nội dung của trang đó. PdfAnnotationEditor.FlatteningAnnotations() (có thể được giới hạn theo phạm vi trang và AnnotationType thông qua overload chấp nhận start, end, và annotType) làm phẳng toàn bộ tài liệu đã ràng buộc trong một lần gọi.

Làm sao tôi có thể xóa tất cả các chú thích của một loại khỏi tài liệu?

Ràng buộc tài liệu bằng PdfAnnotationEditor.BindPdf(), gọi DeleteAnnotations(annotType) với mục tiêu AnnotationType, sau đó Save() kết quả.

API Reference Tóm tắt

Xem thêm

• Aspose.PDF — Enterprise Documentation