파사드 API

파사드 API

A facade 핵심을 기반으로 하는 단순화된 작업 지향 래퍼입니다 Document / Page / Annotation 객체 모델. 페이지 트리를 직접 탐색하는 대신, 소스 PDF에 파사드를 바인딩하고, 소수의 고수준 메서드를 호출한 뒤 결과를 저장합니다. 모든 파사드는 Aspose::Pdf::Facades 정의된 동일한 최소 계약을 구현합니다 IFacade (BindPdf, Close) 그리고 파사드가 출력을 생성하는 경우, ISaveableFacade (Save). 추상 Facade and SaveableFacade 기본 클래스는 아래의 구체 편집기들이 기반으로 하는 기본 bind/close/save 구현을 제공합니다: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, 그리고 양식 중심의 FormEditor / FormFieldFacade 쌍.

파사드 기본 클래스와 bind/save 라이프사이클

IFacade은 BindPdf(srcFile)을 선언합니다(인-메모리 Document를 받도록 오버로드됨)와 Close()도 선언합니다. ISaveableFacade는 출력을 쓰는 파사드를 위해 Save(destFile)를 추가합니다. Facade은 IFacade을 구현하고 바인드된 Document()을 노출하여 파사드 메서드가 필요한 기능을 다루지 못할 때 핵심 객체 모델로 돌아갈 수 있게 합니다; SaveableFacade는 Facade을 Save 구현과 함께 확장합니다. 아래의 모든 구체 편집기는 이 구조를 상속하므로, 동일한 bind → operate → save 패턴이 전체 파사드 API에 적용됩니다.

AcroForm 필드 채우기 및 편집

FormEditor은 이미 바인드된 문서에서 AcroForm 필드를 추가, 제거, 이름 변경 및 위치 재조정합니다. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury)은 지정된 페이지 좌표에 주어진 FieldType(Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) 유형의 새 필드를 생성합니다. RemoveField, RenameField, MoveField, SetFieldAttribute은 기존 필드를 관리하고, SetFieldScript / AddFieldScript은 JavaScript 액션을 부착합니다. SubmitFlag( SubmitFormFlag 값 — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments, 혹은 Pdf)은 제출 버튼이 폼 데이터를 전송하는 방식을 제어하며, SetSubmitUrl는 대상 엔드포인트를 설정합니다.

각 새 필드의 시각적 모양은 FormEditor.Facade()을 통해 제어되며, 이는 FormFieldFacade을 반환합니다. 해당 Font 속성은 FontStyle 값(Helvetica, HelveticaBold, Courier, TimesRoman, Symbol 및 관련 변형)을 받으며, TextEncoding는 EncodingType(Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257)을 사용합니다. 그리고 BorderStyle / BorderWidth는 필드의 테두리를 설정합니다.

FormEditor editor;
editor.SrcFileName("template.pdf");
editor.DestFileName("output.pdf");
editor.AddField(FieldType::Text, "FirstName", 1, 100, 700, 300, 720);
editor.SetFieldAttribute("FirstName", AnnotationFlags::Print);
editor.Save();

PdfBookmarkEditor를 사용하여 개요 관리

PdfBookmarkEditor은 PDF 개요 항목을 생성, 추출, 수정 및 삭제합니다. CreateBookmarks()은 Bookmarks 컬렉션(각 항목은 중첩 개요를 위한 Title, PageNumber, Action, Level, Open, ChildItems을 포함하는 Bookmark)을 바인드된 문서에 기록합니다. ExtractBookmarks()은 기존 개요를 Bookmarks 컬렉션으로 다시 읽어들이며, DeleteBookmarks()는 선택적 title 필터와 함께 항목을 삭제합니다. ExportBookmarksToXML / ImportBookmarksWithXML는 XML 파일을 통해 개요를 왕복 전송하고, ExtractBookmarksToHTML / ExportBookmarksToHtml는 개요를 HTML 페이지로 렌더링합니다.

PdfBookmarkEditor editor;
editor.BindPdf("input.pdf");
Bookmarks bookmarks = editor.ExtractBookmarks();
editor.DeleteBookmarks("Draft");
editor.Save("output.pdf");

PdfAnnotationEditor를 사용하여 주석 편집

PdfAnnotationEditor은 전체 문서에 걸쳐 주석을 평탄화하고 가져옵니다. FlatteningAnnotations()은 주석을 페이지 내용 스트림에 병합하여 인터랙티브 객체가 아니라 정적 콘텐츠로 렌더링되게 합니다; start/end 페이지 범위와 주석 유형을 지정하는 오버로드는 작업을 제한합니다. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf는 외부 FDF/XFDF 파일에서 주석을 가져오며, DeleteAnnotations()(또는 단일 유형의 경우 DeleteAnnotations(annotType))은 이를 제거합니다.

PdfAnnotationEditor editor;
editor.BindPdf("commented.pdf");
editor.FlatteningAnnotations();
editor.Save("flattened.pdf");

PdfContentEditor를 사용하여 페이지 콘텐츠 재작성

PdfContentEditor은 페이지를 재구성하지 않고 이미 생성된 페이지의 콘텐츠 스트림을 편집합니다. ReplaceText(srcText, destText)은 문서 전체에서 일치하는 텍스트를 찾아 교체하며, 교체 범위를 단일 페이지로 제한하는 오버로드도 제공합니다. ReplaceImage(pageNum, imageNum, fileName)와 DeleteImage(pageNum, imageNum)은 기존 이미지 XObject를 교체하거나 제거합니다. DeleteStampById / HideStampById / ShowStampById / MoveStampById은 페이지의 스탬프 객체를 관리합니다(스탬프의 기본 콘텐츠는 StampType 열거형에 따라 Form 또는 Image 중 하나입니다). 또한 AddDocumentAdditionalAction / AddDocumentAttachment는 문서 수준의 JavaScript 동작 및 파일 첨부를 연결합니다.

PdfContentEditor editor;
editor.BindPdf("template.pdf");
editor.ReplaceText("{{CustomerName}}", "Jane Doe");
editor.Save("output.pdf");

PdfExtractor를 사용하여 텍스트 및 첨부 파일 추출

PdfExtractor은 BindPdf과 함께 바인드되거나 이미 열린 Document에서 직접 생성될 수 있습니다. ExtractText()은 HasNextPageText() / GetNextPageText(outputFile)와 함께 문서를 페이지별로 순회합니다. 임베디드 파일의 경우, GetAttachNames()은 존재하는 첨부 파일을 나열하고 GetAttachment( outputPath)은 다음 파일을 디스크에 기록합니다:

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

int main() {
    Aspose::Pdf::Document doc("attachments.pdf");
    Aspose::Pdf::Facades::PdfExtractor extractor(doc);

    auto names = extractor.GetAttachNames();
    std::cout << "Attachments found: " << names.size() << "\n";

    if (!names.empty()) {
        extractor.GetAttachment("extracted-attachment.bin");
    }
}

ExtractImage() / HasNextImage() / GetNextImage(outputFile) 은(는) GetNextPageText 가 페이지를 넘기는 것과 같은 방식으로 내장된 래스터 이미지를 추출합니다.

PdfFileEditor 로 파일을 조립하고 분할합니다.

PdfFileEditor 은(는) 바인드된 Document 대신 파일 경로에서 작동하므로 모든 메서드는 입력/출력 파일명을 직접 받습니다. Concatenate (및 예외를 발생시키지 않는 TryConcatenate) 은 두 개 이상의 파일을 병합합니다; Append 은 한 파일의 페이지 범위를 다른 파일에 삽입합니다; Extract 은 페이지 범위 또는 단일 페이지를 새 파일로 추출합니다; Delete 은 페이지를 제거합니다; 그리고 SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks 은 문서를 페이지별로, 페이지 단위로, 또는 고정 크기 청크로 나눕니다. MakeBooklet 과 MakeNUp 은 소책자 또는 N-up 인쇄를 위해 페이지 순서를 재배열하고, ResizeContents / AddMargins / AddPageBreak 은 파일 전체의 페이지 기하학을 조정합니다. 대부분의 작업에는 실패 시 예외를 발생시키는 대신 false 을 반환하는 Try-접두사가 붙은 대응 함수가 있습니다.

PdfFileEditor editor;
editor.Concatenate("part1.pdf", "part2.pdf", "merged.pdf");
editor.Extract("merged.pdf", 1, 3, "first-three-pages.pdf");

PdfConverter 로 페이지를 이미지로 렌더링합니다.

PdfConverter 은(는) 바인드된 문서 페이지를 래스터 형식으로 렌더링합니다. DoConvert() 은(는) 페이지 범위 (StartPage / EndPage) 를 반복을 위해 준비합니다; HasNextImage () / GetNextImage(outputFile) 는 페이지를 하나씩 순차적으로 진행합니다. SaveAsTIFF 은 전체 범위를 단일 다중 페이지 TIFF 파일에 기록하며, 해상도, 압축 및 TiffSettings 에 대한 오버로드를 제공합니다. RenderingOptions 과 Resolution 은 래스터화 품질을 제어하고, ImageMergeMode (Vertical, Horizontal, Center) 은 호출자가 여러 렌더링된 페이지 이미지를 하나의 이미지로 병합할 때 결합 방식을 관리합니다.

PdfConverter converter;
converter.BindPdf("report.pdf");
converter.Resolution(Aspose::Pdf::Devices::Resolution(150));
converter.DoConvert();
while (converter.HasNextImage()) {
    converter.GetNextImage("page.png");
}

PdfFileSecurity 로 문서를 암호화합니다.

PdfFileSecurity 은(는) 소스 파일을 바인드하고 암호화를 적용하거나 제거합니다. EncryptFile(userPassword, ownerPassword, privilege, keySize) 은(는) DocumentPrivilege (기본 생성자와 AllowPrint, AllowCopy, AllowModifyContents 와 같은 불리언 세터로 구성) 와 KeySize (x40, x128, 또는 x256) 로 암호화합니다; 다섯 번째 cipher 인수를 받는 오버로드는 Algorithm (RC4 또는 AES) 을 명시적으로 선택합니다. DecryptFile( ownerPassword), ChangePassword, SetPrivilege 은 남은 비밀번호 관리 경우를 다루며, 각각 예외를 발생시키지 않는 Try-접두사 변형이 있습니다.

PdfFileSecurity security;
security.BindPdf("input.pdf");

DocumentPrivilege privilege;
privilege.AllowPrint(true);
privilege.AllowModifyContents(false);

security.EncryptFile("user-pass", "owner-pass", privilege, KeySize::x256);

PdfFileSignature 로 서명하고 검증합니다.

PdfFileSignature은(는) 바인드된 문서의 디지털 서명을 서명하고, 인증하고, 검사합니다. Sign(sigName, reason, contact, location, signature)은(는) 기존 서명 필드에 새 서명을 적용하고; Certify은(는) 인증 서명을 적용합니다. GetSignatureNames(onlyEmpty)과 GetBlankSignatureNames()는 문서의 서명 필드를 SignatureName 값으로 반환하며, VerifySignature(sigName) / IsCoversWholeDocument (sigName)은(는) 유효성 및 범위를 확인합니다. RemoveSignature과 RemoveSignatures()는 기존 서명을 제거하고, SetCertificate(pfxFile, password)은(는) Sign을(를) 호출하기 전에 서명 자격 증명을 제공합니다.

PdfFileSignature signature;
signature.BindPdf("contract.pdf");
signature.SetCertificate("signing-cert.pfx", "cert-password");
bool signed_ok = signature.ContainsSignature();
signature.Save();

PdfFileStamp으로 머리글, 바닥글 및 페이지 번호를 스탬프합니다.

PdfFileStamp은(는) 바인드된 파일의 모든 페이지에 반복되는 콘텐츠를 오버레이합니다. AddPageNumber(format)은(는) 시작 번호와 선택적 명시 좌표를 사용하여 페이지 번호 레이블을 스탬프합니다; AddHeader(text, topMargin)와 AddFooter(text, bottomMargin)은(는) 지정된 여백에 반복되는 머리글/바닥글 텍스트를 추가하며, 좌우 여백에 대한 오버로드를 제공합니다. KeepSecurity는 출력 파일의 기존 암호화를 보존하고, Close()는 바인드된 문서를 최종화하고 해제합니다.

PdfFileStamp stamp;
stamp.InputFile("input.pdf");
stamp.OutputFile("stamped.pdf");
stamp.AddPageNumber("Page # of #", 1);
stamp.Close();

PdfFileInfo으로 문서 정보를 읽고 씁니다.

PdfFileInfo은(는) 전체 객체 모델을 열지 않고 고전 PDF /Info 사전과 기본 페이지별 기하 정보를 읽고 다시 씁니다. Author, Title, Subject, Keywords, CreationDate, ModDate은(는) 읽기/쓰기 속성이고; Producer와 GetPdfVersion()은(는) 읽기 전용입니다. GetPageWidth, GetPageHeight, GetPageRotation는 페이지 번호별 페이지 기하 정보를 반환하며, IsEncrypted() / HasOpenPassword() / HasEditPassword()는 문서의 보호 상태를 보고합니다. SaveNewInfo(outputFile)은(는) 변경 사항을 다시 기록합니다.

PdfFileInfo info;
info.BindPdf(document);
info.Title("Updated Report Title");
info.SaveNewInfo("output.pdf");

PdfPageEditor으로 페이지를 재배치합니다.

PdfPageEditor은(는) 페이지 콘텐츠를 블록 단위로 이동, 크기 조정 및 회전시킵니다. MovePosition(offsetX, offsetY)은(는) ProcessPages가 선택한 페이지의 콘텐츠를 이동시키고; Zoom은(는) 이를 스케일링합니다. Alignment ( AlignmentType — Left, Center 또는 Right 중 하나이며, 각각 해당 정적 메서드에서 얻음)와 VerticalAlignment ( VerticalAlignmentType — Top, Center, Bottom 중 하나) 는 ApplyChanges()가 실행된 후 대상 PageSize 내에서 콘텐츠가 배치되는 방식을 제어합니다. GetPageRotation은(는) 페이지의 현재 회전 각도를 도 단위로 읽어옵니다.

PdfPageEditor editor;
editor.BindPdf("input.pdf");
editor.Alignment(AlignmentType::Center());
editor.MovePosition(0, -20);
editor.ApplyChanges();

PdfXmpMetadata으로 XMP 메타데이터를 관리합니다.

PdfXmpMetadata은(는) 문서의 XMP 패킷에 대한 맵 같은 파사드입니다. Add(key, value), Remove(key), Contains(key) / ContainsKey(key), 및 TryGetValue(key, value)는 개별 항목을 관리하고; Keys()와 Values()은 전체 패킷을 열거합니다. RegisterNamespaceURI(prefix, namespaceURI)은(는) 해당 네임스페이스에 속성을 추가하기 전에 사용자 정의 XMP 네임스페이스를 선언합니다. 잘 알려진 속성 이름은 DefaultMetadataProperties(CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails 등) 에 나열되어 있으며, PropertyFlag(ReadOnly, Required, NoExport)은(는) 등록된 속성의 스키마 제약을 설명합니다.

PdfXmpMetadata xmp;
xmp.BindPdf(document);
xmp.Add("dc:creator", "Report Generator");
xmp.Save("output.pdf");

팁 및 모범 사례

• 모든 파사드는 동일한 BindPdf(또는 파일명을 받는 생성자) → 작동 → Save/Close 순서를 따릅니다 — 하나의 파사드를 배우면 다음 파사드에 바로 적용됩니다.
• 신뢰할 수 없거나 예측 불가능한 소스에서 파일을 처리할 때는 PdfFileEditor와 PdfFileSecurity의 Try-접두사 메서드를 사용하는 것이 좋습니다 — 오류 발생 시 예외를 발생시키는 대신 false을 반환합니다.
• PdfFileEditor 메서드는 파일 경로를 받으며, 바인드된 Document을 받지 않습니다 — Concatenate, Extract, 또는 SplitFromFirst를 호출하기 전에 소스 파일을 직접 열 필요가 없습니다.
• 파사드는 핵심 객체 모델을 대체하지 않고 래핑합니다: Facade은(는) 파사드 메서드가 다루지 않는 경우를 위해 기본 Document()을 노출합니다.
• 바인드된 문서 사용을 마쳤을 때 Close()을 호출하거나(지원되는 경우 파사드가 스코프를 벗어나도록) 기본 파일 핸들을 해제합니다.

일반적인 문제

FAQ

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

Facade는 양식 작성, 파일 병합, 페이지 스탬프와 같은 단일 작업을 위한 작고 작업 지향적인 메서드 인터페이스를 제공합니다. 핵심 API (Document, Page, Annotation)는 모든 PDF 객체에 대한 완전한 접근을 제공합니다. Facade 기본 클래스를 통해 Document()을 노출하는 Facade는 Facade 메서드가 다루지 않는 경우 핵심 모델로 돌아갈 수 있게 합니다.

각 Facade 메서드 호출 전에 BindPdf을 호출해야 하나요?

예, IFacade을 구현하는 Facade의 경우 — BindPdf(또는 PdfExtractor(doc)와 같은 동등한 생성자 오버로드) 를 바인딩된 문서를 읽거나 수정하는 모든 작업 전에 실행해야 합니다.

PdfFileEditor 작업을 체인 형태로 연결할 수 있나요?

각 PdfFileEditor 메서드는 자체 입력 파일을 읽고 자체 출력 파일을 씁니다. 따라서 한 메서드의 출력 파일을 다음 메서드의 입력 파일로 전달하여 작업을 연결합니다 — 예를 들어, Concatenate을 merged.pdf에 전달하고, 그 다음 merged.pdf에서 Extract을 수행합니다.

어떤 Facade가 예외를 발생시키지 않는 오류 모드를 지원하나요?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, 및 관련 Try* 메서드)와 PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword)는 모두 Try-접두사가 붙은 대안을 제공하여 예외를 발생시키는 대신 bool를 반환합니다.

API Reference 요약

참조

• Aspose.PDF — Enterprise Documentation