파사드 API를 Aspose.PDF FOSS for C++에서 사용하는 방법

Aspose.PDF FOSS for C++는 Aspose::Pdf::Facades 네임스페이스에 고수준 파사드 및 에디터 클래스 집합을 그룹화합니다 — PdfExtractor, PdfBookmarkEditor, PdfContentEditor, PdfAnnotationEditor, FormEditor, PdfFileEditor, 그리고 PdfConverter 등이 포함됩니다. 각각은 핵심 Document API 위에 단일 문서 유지 관리 작업을 래핑하므로, 페이지와 객체 탐색을 직접 구현하지 않고도 콘텐츠를 추출하고, 북마크를 편집하며, 양식 필드를 채울 수 있습니다. 이 가이드는 기존 PDF에서 임베디드 파일 첨부, 페이지 텍스트 및 임베디드 이미지를 추출하는 데 사용되는 파사드인 PdfExtractor에 초점을 맞춥니다.

단계별 가이드

1단계: 패키지 설치

Aspose.PDF FOSS for C++를 CMake 서브디렉터리로 추가하고 정적 라이브러리 타깃을 링크합니다:

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp.git

add_subdirectory(Aspose.PDF-FOSS-for-Cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

파사드 코드를 작성하기 전에 툴체인 및 링크 단계가 올바르게 해결되는지 확인하십시오:

cmake -S . -B build
cmake --build build

C++20 컴파일러를 사용한 클린 빌드가 aspose_pdf_foss가 your_app에 링크되었음을 확인합니다.

단계 2: 필요한 클래스 가져오기

PdfExtractor는 aspose/pdf/facades/ 아래에 위치하며, 코어 네임스페이스의 Document와 함께 있습니다:

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/facades/pdf_extractor.hpp>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Facades;

단계 3: 문서를 PdfExtractor에 바인딩하기

모든 파사드 클래스는 공통 Facade 기반을 상속받으며, 이 기반은 BindPdf(srcFile) 및 BindPdf(srcDoc)를 노출하여 생성 후 문서에 연결할 수 있게 합니다. PdfExtractor는 또한 이미 열린 Document를 생성자에서 직접 받아들이며, 이는 이 가이드 전반에 사용되는 패턴입니다:

Document doc("input.pdf");
PdfExtractor extractor(doc);

단계 4: 내장 파일 첨부 파일 추출하기

Document::EmbeddedFiles()를 먼저 확인하고, 그 다음 GetAttachNames()으로 첨부 파일 이름을 읽으며, GetAttachment()를 사용해 첨부 파일의 바이트를 디스크에 저장합니다:

#include <iostream>

if (doc.EmbeddedFiles().Count() > 0) {
    std::vector<std::string> names = extractor.GetAttachNames();
    for (const auto& name : names) {
        std::cout << "Attachment: " << name << "\n";
    }

    // Writes the bytes of the first attachment to disk
    extractor.GetAttachment("extracted_attachment.bin");
}

단계 5: 모든 페이지에서 텍스트 추출하기

ExtractText()에 이어 GetText()을 사용하면 전체 문서의 텍스트를 하나의 파일에 기록합니다:

extractor.ExtractText();
extractor.GetText("extracted_text.txt");

대신 페이지당 하나의 파일을 캡처하려면, StartPage() / EndPage() 로 페이지 범위를 설정한 다음, 루프에서 HasNextPageText() / GetNextPageText() 를 구동하여 각 호출마다 자체 출력 경로를 지정합니다:

extractor.StartPage(1);
extractor.EndPage(doc.Pages().Count());

int pageNumber = extractor.StartPage();
while (extractor.HasNextPageText()) {
    std::string outputFile = "page_" + std::to_string(pageNumber) + ".txt";
    extractor.GetNextPageText(outputFile);
    ++pageNumber;
}

단계 6: 포함된 이미지 추출

ExtractImage()은(는) 이미지 커서를 초기화합니다; HasNextImage() / GetNextImage()은(는) 그런 다음 이미지를 하나씩 순회하면서 전달한 경로에 각각 기록합니다:

extractor.ExtractImage();

int imageIndex = 1;
while (extractor.HasNextImage()) {
    std::string outputFile = "extracted_image_" + std::to_string(imageIndex);
    if (extractor.GetNextImage(outputFile)) {
        ++imageIndex;
    }
}

일반적인 문제 및 해결 방법

GetAttachNames() 빈 벡터를 반환합니다. 원본 PDF에 삽입된 파일이 없습니다. 확인 doc.EmbeddedFiles().Count() 어떤 첨부 메서드를 호출하기 전에 PdfExtractor 첨부 파일이 전혀 없었던 문서에서 추출을 시도하지 않도록 합니다.

페이지 텍스트 루프가 본문에 들어가지 않습니다. HasNextPageText() returns false 즉시 if StartPage() / EndPage() 설정되지 않았거나, 문서 실제 페이지 수 범위 밖으로 설정된 경우입니다. 범위를 명시적으로 다음에서 설정하십시오 doc.Pages().Count() 확인하기 전에 HasNextPageText().

GetNextImage() returns false 첫 번째 호출 시. ExtractImage() 이미지 커서를 초기화하기 위해 한 번 호출되어야 합니다, 확인하기 전에 HasNextImage() 또는 호출 GetNextImage(). 호출 GetNextImage() 사전 없이 ExtractImage() 호출 ExtractImage() 먼저.

추출된 모든 이미지 또는 페이지 텍스트 파일은 이전 파일을 덮어씁니다. GetNextImage() and GetNextPageText() 각각은 문자 그대로의 출력 경로를 사용합니다; 파사드는 여러분을 위해 고유한 파일 이름을 생성하지 않습니다. 반복마다 별도의 경로를 만들고(예: 증가하는 카운터를 추가하여) Steps 5와 6에 표시된 대로 수행하십시오.

링크 오류: 정의되지 않은 참조: aspose_pdf_foss 기호. Confirm add_subdirectory() 클론된 저장소 루트를 가리키고, 그 target_link_libraries() 이름을 aspose_pdf_foss 대상을 정확히 지정하고, C++20 표준을 구성하여 your_app.

자주 묻는 질문

Facade API와 핵심 Document API의 차이점은 무엇인가요?

핵심 Document API(Document, PageCollection, Annotation 등)는 PDF 객체 모델을 직접 노출합니다. PdfExtractor와 같은 파사드 클래스는 그 위에 위치하며, 특정 다단계 작업(콘텐츠 추출, 북마크 편집, 양식 필드 채우기)을 보다 좁고 목적에 맞게 설계된 인터페이스 뒤에 패키징합니다.

제가 PdfExtractor으로 콘텐츠를 추출하는 것과 같은 방식으로 북마크를 편집하거나 양식 필드를 채울 수 있나요?

예. PdfBookmarkEditor(CreateBookmarks(), ModifyBookmarks(), ExtractBookmarks(), DeleteBookmarks()와 함께)와 FormEditor(AddField(), RemoveField(), SetFieldAttribute()와 함께)는 동일한 Aspose::Pdf::Facades 네임스페이스에 존재하며, 단계 2와 3에 표시된 동일한 include/construct 패턴을 따릅니다 — 각각은 문서의 다른 부분을 작업할 뿐입니다.

PdfExtractor이 비밀번호로 보호된 PDF를 읽을 수 있나요?

추출 메서드를 호출하기 전에 비밀번호를 설정하십시오:

extractor.Password("owner-or-user-password");

PdfExtractor::Password()은 단순 읽기/쓰기 속성이므로 ExtractText(), ExtractImage() 또는 첨부 메서드보다 먼저 설정해야 합니다.

PDF에 추출할 텍스트, 이미지, 혹은 첨부 파일이 없으면 어떻게 됩니까?

예외가 발생하지 않습니다. GetAttachNames()은 빈 벡터를 반환하고, HasNextPageText() / HasNextImage()는 첫 번째 검사에서 false을 반환하므로 해당 루프 본문은 실행되지 않습니다.

특정 파사드 클래스에 포함할 헤더는 무엇입니까?

각 파사드 클래스는 aspose/pdf/facades/ 아래에 클래스 이름과 일치하는 자체 헤더를 제공하며, PdfExtractor에 대해서는 pdf_extractor.hpp을, PdfBookmarkEditor에 대해서는 pdf_bookmark_editor.hpp을, FormEditor에 대해서는 form_editor.hpp를, 그리고 Bookmark / Bookmarks 값 유형에 대해서는 bookmark.hpp을 제공합니다.