C++에서 PDF 주석 작업하기

Aspose.PDF FOSS for C++는 모든 PDF 주석을 공통 Annotation 기본 클래스의 서브클래스로 표현하고, Page::Annotations()가 반환하는 AnnotationCollection을 통해 페이지상의 주석을 노출합니다. 이 가이드는 TextAnnotation을 사용하여 페이지에 일반 텍스트 메모 주석과 스타일이 적용된 주석을 추가하고, 문서를 저장한 뒤 다시 열어 주석을 읽어들인 후 하나를 제거합니다. 라이브러리는 CMake 프로젝트에 서브디렉터리 종속성으로 통합되며, 패키지 레지스트리 설치 단계가 없습니다.

단계별 가이드

add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

#include <aspose/pdf/document.hpp>
#include <iostream>

int main() {
    Aspose::Pdf::Document doc;
    std::cout << "Linked OK — pages: " << doc.Pages().Count() << "\n";
}

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/page_collection.hpp>
#include <aspose/pdf/rectangle.hpp>
#include <aspose/pdf/color.hpp>
#include <aspose/pdf/annotations/annotation.hpp>
#include <aspose/pdf/annotations/annotation_collection.hpp>
#include <aspose/pdf/annotations/annotation_type.hpp>
#include <aspose/pdf/annotations/annotation_flags.hpp>
#include <aspose/pdf/annotations/border.hpp>
#include <aspose/pdf/annotations/border_style.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc;
Page page = doc.Pages().Add();

TextAnnotation note{doc};
note.Rect(Rectangle(100.0, 700.0, 200.0, 720.0, false));
note.Contents("Reviewed and approved.");

page.Annotations().Add(note);

TextAnnotation flagged{doc};
flagged.Rect(Rectangle(100.0, 600.0, 300.0, 650.0, false));
flagged.Contents("Needs follow-up");
flagged.Color(Color::FromRgb(220, 20, 20));
flagged.Flags(AnnotationFlags::Print | AnnotationFlags::ReadOnly);
flagged.Border().Width(2);
flagged.Border().Style(BorderStyle::Dashed);

page.Annotations().Add(flagged);

doc.Save("annotated.pdf");

Document reopened("annotated.pdf");
auto& annots = reopened.Pages()[1].Annotations();

std::cout << "Annotation count: " << annots.Count() << "\n";

for (int i = 0; i < annots.Count(); ++i) {
    const auto& a = annots[i];
    if (a.AnnotationType() == AnnotationType::Text) {
        std::cout << "Text annotation: " << a.Contents() << "\n";
    }
}

annots.Delete(0);
reopened.Save("annotated-cleaned.pdf");

일반적인 문제 및 해결 방법

호출한 후 저장된 PDF에 아무 변화가 없습니다 Annotations().Add()

두 가지가 여기서 흔히 잘못됩니다. 첫째, PageCollection은 1 기반(doc.Pages()[1]이 첫 페이지)이고 AnnotationCollection는 0 기반(annots[0]이 첫 주석)입니다 — 두 인덱싱 방식을 혼동하면 잘못된 객체를 조작하게 됩니다. 둘째, Document::Save()가 주석이 추가된 후에 실제로 실행되는지 확인하십시오; 그때까지는 디스크에 아무 것도 기록되지 않습니다.

AnnotationCollection 인덱싱 또는 Delete(index) throws std::out_of_range

유효한 인덱스는 0부터 Count() - 1까지입니다. 음수 인덱스이거나 Count()와 같거나 큰 인덱스를 전달하면 설계상 std::out_of_range가 발생합니다. 루프나 조회를 제한하려면 먼저 Count()를 호출하십시오.

Remove() returns false 같은 주석에 대해 두 번째로 호출할 때

이는 오류가 아닙니다. Remove()은 주석이 bool으로 찾아지고 제거되었는지 보고합니다; 이미 사라진 주석에 다시 호출하면 아무 작업도 수행하지 않으며 false를 반환합니다. Remove()이 항상 성공한다고 가정하지 말고 반환 값을 확인하십시오.

새로운 값을 설정하면 AnnotationFlags 값이 이미 설정한 플래그를 지웁니다

Flags(value)은 전체 플래그 세트를 교체합니다 — 이전 값과 병합되지 않습니다. 단일 플래그를 추가하거나 삭제하려면 먼저 현재 플래그를 읽고 비트 연산자로 결합하십시오, 예를 들어 플래그를 추가하려면 a.Flags(a.Flags() | AnnotationFlags::Print), 나머지는 그대로 두고 하나의 플래그만 삭제하려면 a.Flags(a.Flags() & ~AnnotationFlags::Print)를 사용합니다.

자주 묻는 질문

Annotation, TextAnnotation 및 다른 주석 하위 유형 간의 관계는 무엇입니까?

Annotation은 공통 기본 클래스입니다. TextAnnotation 및 다른 구체적인 주석 유형은 각각 하나의 PDF 주석 하위 유형에 대해 이를 특수화하며, 기본 클래스의 Rect(), Contents(), Color(), Flags(), Border() 접근자를 공유합니다.

주석은 전체 문서에 적용되나요, 아니면 한 페이지에만 적용되나요?

각 페이지는 해당 페이지의 Annotations() 메서드가 반환하는 고유한 AnnotationCollection을 가지고 있습니다. 주석은 항상 추가된 페이지에만 적용되며, 전체 문서 전체에 적용되지 않습니다.

페이지에 있는 주석 수를 어떻게 셀 수 있나요?

Page::Annotations()가 반환하는 AnnotationCollection에 대해 Count()을 호출하세요.

주석이 동시에 인쇄 가능하고 읽기 전용일 수 있나요?

예. AnnotationFlags은 비트 필드이므로 비트 OR 연산자로 값을 결합하면 됩니다. 예를 들어 AnnotationFlags::Print | AnnotationFlags::ReadOnly.

AnnotationCollection에서 주석을 삭제하면 디스크에 있는 PDF 파일에서도 제거됩니까?

Document::Save()가 실행된 후에만. Delete(), Remove(), Clear()는 메모리 컬렉션만 수정합니다 — 문서를 저장할 때까지 디스크상의 PDF는 변경되지 않습니다.

참조

• PDF 주석 작업 (개발자 가이드)
• 설치 가이드
• API Reference
• Aspose.PDF FOSS for C++ — 제품 페이지
• GitHub 리포지토리
• Aspose.PDF for C++ — Enterprise Knowledge Base