ทำงานกับหมายเหตุ 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() นอกจากนี้ยังรองรับเค้าโครง 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 ที่กำลังมองอยู่ได้อย่างไร?

เรียก 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(), เรียก DeleteAnnotations(annotType) พร้อมกับเป้าหมาย AnnotationType, แล้ว Save() ผลลัพธ์.

API Reference สรุป

ดูเพิ่มเติม

• Aspose.PDF — Enterprise Documentation