Dart API 레퍼런스
PDF Oxide는 네이티브 C ABI 위에 dart:ffi로 구축한 관용적인 Dart/Flutter 바인딩을 제공합니다. 이 패키지는 런타임에 미리 빌드된 libpdf_oxide.{so,dylib,dll}을 로드하고 전체 기능을 노출합니다 — 추출, 편집, 생성, 렌더링, 폼, OCR, 바코드, 디지털 서명, 규격 적합성 검증까지.
dart pub add pdf_oxide
import 'package:pdf_oxide/pdf_oxide.dart';
네이티브 핸들은 NativeFinalizer가 자동으로 해제하지만, 핸들을 소유하는 모든 클래스는 멱등한 close()도 함께 노출하므로 작업이 끝나면 호출하는 것이 좋습니다(또는 addTearDown/try/finally를 사용하세요). C-ABI 에러 코드는 PdfOxideError로 던져집니다. 모든 페이지 인덱스는 0부터 시작합니다.
다른 언어는 Python API 레퍼런스, Node.js API 레퍼런스 또는 WASM API 레퍼런스, Rust API 레퍼런스, 타입 & 열거형을 참고하세요.
PdfDocument
PDF를 열고, 추출하고, 렌더링하고, 검증하고, 검사하는 핵심 클래스입니다.
생성자 / 팩토리
static PdfDocument open(String path)
static PdfDocument openFromBytes(Uint8List data)
static PdfDocument openWithPassword(String path, String password)
static PdfDocument openFromDocxBytes(Uint8List data)
static PdfDocument openFromPptxBytes(Uint8List data)
static PdfDocument openFromXlsxBytes(Uint8List data)
open— 파일 시스템 경로에서 PDF를 엽니다.openFromBytes— 메모리 내 바이트에서 PDF를 엽니다.openWithPassword— 비밀번호로 보호된 PDF를 엽니다.openFromDocxBytes/openFromPptxBytes/openFromXlsxBytes— DOCX/PPTX/XLSX 바이트에서 직접 문서를 엽니다.
문서 정보
int get pageCount
PdfVersion get version
bool isEncrypted()
bool hasStructureTree()
bool authenticate(String password)
pageCount— 페이지 수.version—PdfVersion(major, minor)형태의 PDF 버전.isEncrypted— 문서가 암호화되었는지 여부.hasStructureTree— 구조 트리를 가진 태그된(Tagged) PDF인지 여부.authenticate— 암호화된 PDF를 인증합니다. 성공 시true, 잘못된 비밀번호 시false를 반환합니다.
텍스트 & 변환
String extractText(int page)
String toPlainText(int page)
String toMarkdown(int page)
String toHtml(int page)
String extractStructuredJson(int page)
String toMarkdownAll()
String toHtmlAll()
String toPlainTextAll()
extractText— 단일 페이지의 일반 추출 텍스트.toPlainText/toMarkdown/toHtml— 단일 페이지를 일반 텍스트, Markdown, HTML로 변환합니다.extractStructuredJson— 구조화된 페이지 콘텐츠(span, 레이아웃)를 JSON으로 직렬화합니다.toMarkdownAll/toHtmlAll/toPlainTextAll— 문서 전체를 변환합니다.
요소 추출
List<Char> extractChars(int page)
List<Word> extractWords(int page)
List<TextLine> extractTextLines(int page)
List<Table> extractTables(int page)
List<Font> embeddedFonts(int page)
String embeddedFontsJson(int page)
List<double> embeddedFontSizes(int page)
List<Image> embeddedImages(int page)
List<Annotation> pageAnnotations(int page)
List<AnnotationDetails> pageAnnotationDetails(int page)
String annotationsToJson(int page)
List<Path> extractPaths(int page)
extractChars/extractWords/extractTextLines— 글리프별, 단어별, 줄별 기하 정보.extractTables— 셀을 지연 읽기(Table.cell)하는 감지된 테이블.embeddedFonts/embeddedFontsJson/embeddedFontSizes— 페이지의 임베드 폰트 메타데이터.embeddedImages— 원시 바이트를 포함한 임베드 이미지.pageAnnotations— 페이지의 주석.pageAnnotationDetails— 확장 주석 속성(플래그, 날짜, 색상, 링크 URI, 아이콘 이름, quad point).annotationsToJson— 주석을 JSON으로 직렬화합니다.extractPaths— 벡터 경로(그래픽) 요소.
사각형 영역 추출
String extractTextInRect(int page, double x, double y, double w, double h)
List<Word> extractWordsInRect(int page, double x, double y, double w, double h)
List<TextLine> extractLinesInRect(int page, double x, double y, double w, double h)
List<Table> extractTablesInRect(int page, double x, double y, double w, double h)
List<Image> extractImagesInRect(int page, double x, double y, double w, double h)
페이지의 사각형(PDF 사용자 공간 포인트)으로 제한하여 텍스트, 단어, 줄, 테이블, 이미지를 추출합니다.
자동 추출 & 분류
String extractTextAuto(int page)
String extractPageAuto(int page, [String optionsJson = ''])
String extractAllText()
String classifyPage(int page)
String classifyDocument()
extractTextAuto— 필요에 따라 네이티브 + 이미지 OCR 추출을 페이지에 적용합니다.extractPageAuto— 선택적 JSON 옵션과 함께 단일 페이지를 자동 추출합니다.extractAllText— 모든 페이지의 텍스트를 하나의 문자열로.classifyPage/classifyDocument— 페이지/문서를 JSON으로 분류합니다(스캔본, 디지털, 하이브리드 등).
검색
List<SearchResult> search(int page, String term, bool caseSensitive)
List<SearchResult> searchAll(String term, bool caseSensitive)
String searchResultsToJson(int page, String term, bool caseSensitive)
단일 페이지, 문서 전체를 검색하거나, 페이지 일치 결과를 JSON으로 직렬화합니다.
렌더링
RenderedImage renderPage(int pageIndex, [int format = 0])
RenderedImage renderPageZoom(int pageIndex, double zoom, [int format = 0])
RenderedImage renderPageThumbnail(int pageIndex, int size, [int format = 0])
RenderedImage renderPageWithOptions(int pageIndex, {int dpi = 150, int format = 0, double backgroundR = 1.0, double backgroundG = 1.0, double backgroundB = 1.0, double backgroundA = 1.0, bool transparentBackground = false, bool renderAnnotations = true, int jpegQuality = 90})
RenderedImage renderPageWithOptionsEx(int pageIndex, {int dpi = 150, int format = 0, double backgroundR = 1.0, double backgroundG = 1.0, double backgroundB = 1.0, double backgroundA = 1.0, bool transparentBackground = false, bool renderAnnotations = true, int jpegQuality = 90, List<String> excludedLayers = const []})
RenderedImage renderPageRegion(int pageIndex, double cropX, double cropY, double cropWidth, double cropHeight, [int format = 0])
RenderedImage renderPageFit(int pageIndex, int width, int height, [int format = 0])
RenderedImage renderPageRaw(int pageIndex, [int dpi = 150])
int estimateRenderTime(int pageIndex)
renderPage— 페이지를RenderedImage로 렌더링합니다(format0=PNG, 1=JPEG).renderPageZoom— 확대 배율로 렌더링합니다.renderPageThumbnail—size픽셀 안에 들어가는 썸네일을 렌더링합니다.renderPageWithOptions— 전체 RenderOptions 표면(dpi, 배경, 주석, JPEG 품질).renderPageWithOptionsEx—excludedLayers를 통해 이름 있는 OCG 레이어 억제를 추가합니다.renderPageRegion— 사각형 영역을 렌더링합니다.renderPageFit— 종횡비를 유지하면서width×height안에 맞도록 렌더링합니다.renderPageRaw—dpi에서 원시 premultiplied RGBA8888 버퍼로 렌더링합니다.estimateRenderTime— 페이지의 렌더링 시간(ms)을 추정합니다.
페이지 기하 & 요소
double pageWidth(int pageIndex)
double pageHeight(int pageIndex)
int pageRotation(int pageIndex)
ElementList pageElements(int pageIndex)
Page page(int index)
pageWidth/pageHeight— PDF 포인트 단위의 페이지 크기.pageRotation— 도(degree) 단위의 페이지 회전.pageElements— 페이지의 레이아웃 요소를ElementList로.page— 페이지별 추출을 체이닝하기 위한 가벼운Page뷰.
OCR
bool pageNeedsOcr(int pageIndex)
String ocrExtractText(int pageIndex, [OcrEngine? engine])
pageNeedsOcr— 페이지가 스캔본/하이브리드여서 OCR이 필요한지 여부.ocrExtractText— OCR로 텍스트를 추출합니다.engine이 null이면 네이티브 추출만 수행합니다.
규격 적합성 검증 & 변환
PdfAResults validatePdfA(int level)
UaResults validatePdfUa(int level)
PdfXResults validatePdfX(int level)
bool convertToPdfA(int level)
validatePdfA/validatePdfUa/validatePdfX— PDF/A, PDF/UA 접근성, 또는 PDF/X에 대해 검증합니다.convertToPdfA— 이 문서를 지정한 레벨의 PDF/A로 제자리에서 변환합니다.
Office 내보내기
Uint8List toDocx()
Uint8List toPptx()
Uint8List toXlsx()
Uint8List sourceBytes()
toDocx/toPptx/toXlsx— 문서를 DOCX/PPTX/XLSX 바이트로 내보냅니다.sourceBytes— 이 문서가 로드된 원본 소스 바이트.
머리글 / 바닥글 / 아티팩트 제거
int eraseHeader(int page)
int eraseFooter(int page)
int eraseArtifacts(int page)
int removeHeaders([double threshold = 0.5])
int removeFooters([double threshold = 0.5])
int removeArtifacts([double threshold = 0.5])
eraseHeader/eraseFooter/eraseArtifacts— 페이지의 머리글, 바닥글, 또는 표시된 아티팩트를 지웁니다. 지운 항목 수를 반환합니다.removeHeaders/removeFooters/removeArtifacts— 감지 임계값을 사용해 문서 전반에서 반복되는 부속 요소를 제거합니다.
폼
List<FormField> getFormFields()
Uint8List exportFormDataToBytes([int formatType = 0])
void importFormData(String dataPath)
bool importFormFromFile(String filename)
getFormFields— 대화형 AcroForm 필드.exportFormDataToBytes— 폼 데이터를 내보냅니다(formatType0=FDF, 1=XFDF, 2=JSON).importFormData— FDF/XFDF/JSON 파일 경로에서 폼 데이터를 가져옵니다.importFormFromFile— 파일에서 필드 값을 가져옵니다. 가져온 항목이 있는지 여부를 반환합니다.
문서 구조 & 메타데이터
String getOutline()
String getPageLabels()
String getXmpMetadata()
bool hasXfa()
String planSplitByBookmarks([String optionsJson = ''])
getOutline— 문서 개요(북마크)를 JSON으로.getPageLabels— 페이지 라벨 범위를 JSON으로.getXmpMetadata— XMP 메타데이터(XML)가 있으면 반환합니다.hasXfa— 문서에 XFA 폼이 포함되어 있는지 여부.planSplitByBookmarks— 북마크 기준 분할 계획을 JSON으로 생성합니다.
디지털 서명
int sign(Certificate certificate, {String reason = '', String location = ''})
int getSignatureCount()
SignatureInfo getSignature(int index)
int verifyAllSignatures()
bool hasTimestamp()
Dss getDss()
sign—Certificate로 문서에 디지털 서명합니다.getSignatureCount— 존재하는 서명 수.getSignature— 인덱스 위치의SignatureInfo.verifyAllSignatures— 모든 서명을 검증합니다(통합 상태).hasTimestamp— 어떤 서명에든 타임스탬프가 포함되어 있는지 여부.getDss— 문서 보안 저장소(Dss).
수명 주기
void close()
네이티브 핸들을 지금 해제합니다(멱등).
Page
PdfDocument.page(index)가 반환하는, 0부터 시작하는 단일 페이지의 가벼운 뷰입니다. 자신의 문서에 대한 강한 참조를 유지하며 문서의 페이지별 메서드에 위임합니다.
| 멤버 | 타입 | 설명 |
|---|---|---|
index |
int |
0부터 시작하는 페이지 인덱스 |
String text()
String markdown()
String html()
String plainText()
이 페이지의 추출 텍스트, Markdown, HTML, 또는 일반 텍스트입니다.
단순 빌더/저장 흐름을 위해 생성된(또는 로드된) PDF입니다.
팩토리
static Pdf fromMarkdown(String md)
static Pdf fromHtml(String html)
static Pdf fromText(String text)
static Pdf fromImage(String path)
static Pdf fromImageBytes(Uint8List data)
static Pdf fromHtmlCss(String html, String css, [Uint8List? fontBytes])
static Pdf fromHtmlCssWithFonts(String html, String css, List<String> families, List<Uint8List> fonts)
fromMarkdown/fromHtml/fromText— Markdown, HTML, 또는 일반 텍스트에서 PDF를 생성합니다.fromImage/fromImageBytes— 이미지 파일이나 이미지 바이트를 단일 페이지 PDF로 감쌉니다.fromHtmlCss— 선택적 임베드 폰트 하나와 함께 HTML + CSS에서 빌드합니다.fromHtmlCssWithFonts— 병렬families/fonts폰트 캐스케이드와 함께 HTML + CSS에서 빌드합니다.
메서드
int get pageCount
void save(String path)
Uint8List toBytes()
void close()
pageCount—pdf_get_page_count진입점을 통한 페이지 수.save— 파일로 저장합니다.toBytes— PDF 콘텐츠를 바이트로.close— 네이티브 핸들을 해제합니다(멱등).
DocumentEditor
제자리 편집을 위해 열린 PDF입니다: 페이지 작업, 메타데이터, 폼, 교정(redaction), 평면화(flatten), 병합, 암호화 저장.
생성자
static DocumentEditor open(String path)
static DocumentEditor openFromBytes(Uint8List data)
문서 정보 & 메타데이터
int get pageCount
PdfVersion get version
bool isModified()
String getSourcePath()
String getProducer()
void setProducer(String value)
String getCreationDate()
void setCreationDate(String dateStr)
isModified— 저장되지 않은 수정 사항이 있는지 여부.getSourcePath— 에디터가 열린 경로.getProducer/setProducer— Producer 메타데이터 필드.getCreationDate/setCreationDate— CreationDate 메타데이터 필드.
페이지 작업
void deletePage(int pageIndex)
void movePage(int from, int to)
void rotatePageBy(int page, int degrees)
void rotateAllPages(int degrees)
void setPageRotation(int page, int degrees)
int getPageRotation(int page)
void cropMargins(double left, double right, double top, double bottom)
Bbox getPageCropBox(int page)
void setPageCropBox(int page, Bbox box)
Bbox getPageMediaBox(int page)
void setPageMediaBox(int page, Bbox box)
deletePage/movePage— 페이지를 삭제하거나 순서를 바꿉니다.rotatePageBy— 누적 회전.rotateAllPages— 모든 페이지의 상대 회전.setPageRotation— 절대 회전.getPageRotation— 현재 회전.cropMargins— 모든 페이지의 여백을 잘라냅니다.getPageCropBox/setPageCropBox/getPageMediaBox/setPageMediaBox— CropBox/MediaBox를 읽고 씁니다.
교정(Redaction) & 지우기
void applyAllRedactions()
void applyPageRedactions(int page)
void eraseRegion(int page, double x, double y, double w, double h)
void eraseRegions(int page, List<List<double>> rects)
void clearEraseRegions(int page)
bool isPageMarkedForRedaction(int page)
void unmarkPageForRedaction(int page)
void redactionAdd(int page, double x1, double y1, double x2, double y2, {double r = 0.0, double g = 0.0, double b = 0.0})
int redactionCount(int page)
int redactionApply({bool scrubMetadata = false, double r = 0.0, double g = 0.0, double b = 0.0})
int redactionScrubMetadata()
applyAllRedactions/applyPageRedactions— 대기 중인 교정을 적용합니다.eraseRegion/eraseRegions/clearEraseRegions— 하나, 여러 개를 지우거나 대기 중인 지우기 사각형을 비웁니다.isPageMarkedForRedaction/unmarkPageForRedaction— 페이지의 교정 표시를 조회/해제합니다.redactionAdd— 오버레이 채우기 색상과 함께 교정 사각형을 대기열에 넣습니다.redactionCount— 페이지의 대기 중인 교정 영역.redactionApply— 모든 교정을 파괴적으로 적용합니다. 제거된 글리프 수를 반환합니다.redactionScrubMetadata— 메타데이터 / JavaScript / 임베드 파일을 제거합니다. 제거된 구성 요소 수를 반환합니다.
평면화(Flatten)
void flattenForms()
void flattenFormsOnPage(int pageIndex)
void flattenAnnotations(int page)
void flattenAllAnnotations()
int flattenWarningsCount()
String flattenWarning(int index)
bool isPageMarkedForFlatten(int page)
void unmarkPageForFlatten(int page)
flattenForms/flattenFormsOnPage— 모든 폼 필드 또는 한 페이지의 폼 필드를 평면화합니다.flattenAnnotations/flattenAllAnnotations— 한 페이지 또는 문서 전반의 주석을 평면화합니다.flattenWarningsCount/flattenWarning— 마지막 평면화 저장의 경고.isPageMarkedForFlatten/unmarkPageForFlatten— 페이지의 평면화 표시를 조회/해제합니다.
폼
void setFormFieldValue(String name, String value)
void importFdfBytes(Uint8List data)
void importXfdfBytes(Uint8List data)
setFormFieldValue— 이름으로 필드 값을 설정합니다.importFdfBytes/importXfdfBytes— FDF/XFDF 바이트에서 AcroForm 값을 가져옵니다.
병합 / 변환 / 임베드 / 추출
void mergeFrom(String sourcePath)
void mergeFromBytes(Uint8List data)
void convertToPdfA(int level)
void embedFile(String name, Uint8List data)
Uint8List extractPagesToBytes(List<int> pages)
mergeFrom/mergeFromBytes— 디스크 또는 메모리의 PDF에서 페이지를 덧붙입니다.convertToPdfA— PDF/A로 제자리에서 변환합니다(레벨 0=A1b … 7=A3u).embedFile— 이름 있는 파일을 첨부합니다.extractPagesToBytes— 페이지의 부분 집합을 새 메모리 내 PDF로 추출합니다.
바코드
void addBarcodeToPage(int pageIndex, BarcodeImage barcode, double x, double y, double width, double height)
생성된 BarcodeImage를 지정한 사각형 위치로 페이지에 스탬프합니다.
저장
void save(String path)
Uint8List saveToBytes()
Uint8List saveToBytesWithOptions(bool compress, bool garbageCollect, bool linearize)
void saveEncrypted(String path, String userPassword, String ownerPassword)
Uint8List saveEncryptedToBytes(String userPassword, String ownerPassword)
void close()
save/saveToBytes— 파일 또는 바이트 버퍼로 저장합니다.saveToBytesWithOptions— 명시적인 압축 / 가비지 컬렉션 / 선형화 옵션과 함께 저장합니다.saveEncrypted/saveEncryptedToBytes— AES-256으로 암호화하여 파일 또는 바이트로 저장합니다.close— 네이티브 핸들을 해제합니다(멱등).
DocumentBuilder
완전히 새로운 PDF 문서를 조립하기 위한 플루언트(fluent) 빌더입니다.
생성
static DocumentBuilder create()
메타데이터 (플루언트)
DocumentBuilder setTitle(String value)
DocumentBuilder setAuthor(String value)
DocumentBuilder setSubject(String value)
DocumentBuilder setKeywords(String value)
DocumentBuilder setCreator(String value)
DocumentBuilder onOpen(String script)
DocumentBuilder language(String lang)
DocumentBuilder taggedPdfUa1()
DocumentBuilder roleMap(String custom, String standard)
DocumentBuilder registerEmbeddedFont(String name, EmbeddedFont font)
setTitle/setAuthor/setSubject/setKeywords/setCreator— 문서 메타데이터.onOpen— 문서 열기 시 실행되는 JavaScript.language— 문서 언어.taggedPdfUa1— PDF/UA-1 태그 모드를 활성화합니다.roleMap— 사용자 정의 구조 타입을 표준 PDF 타입에 매핑합니다.registerEmbeddedFont— 폰트를 이름으로 등록합니다(성공 시EmbeddedFont을 소비합니다).
페이지
PageBuilder a4Page()
PageBuilder letterPage()
PageBuilder page(double width, double height)
A4, US Letter, 또는 사용자 지정 크기의 페이지를 PageBuilder로 엽니다.
빌드 / 저장
Uint8List build()
void save(String path)
void saveEncrypted(String path, String userPassword, String ownerPassword)
Uint8List toBytesEncrypted(String userPassword, String ownerPassword)
void close()
build— PDF를 빌드하고 바이트를 반환합니다.save— 빌드하여 경로에 저장합니다.saveEncrypted/toBytesEncrypted— AES-256으로 암호화하여 파일 또는 바이트로 빌드합니다.close— 네이티브 핸들을 해제합니다(멱등).
PageBuilder
DocumentBuilder.page / letterPage / a4Page가 반환하는 단일 페이지용 플루언트 빌더입니다. 모든 작업은 체이닝을 위해 this를 반환합니다. 페이지를 커밋하려면 done()을, 폐기하려면 close()를 호출하세요.
텍스트 & 레이아웃
PageBuilder font(String name, double size)
PageBuilder at(double x, double y)
PageBuilder text(String value)
PageBuilder heading(int level, String value)
PageBuilder paragraph(String value)
PageBuilder space(double points)
PageBuilder horizontalRule()
PageBuilder columns(int columnCount, double gapPt, String value)
PageBuilder inline(String value)
PageBuilder inlineBold(String value)
PageBuilder inlineItalic(String value)
PageBuilder inlineColor(double r, double g, double b, String value)
PageBuilder newline()
PageBuilder footnote(String refMark, String noteText)
PageBuilder textInRect(double x, double y, double w, double h, String value, int align)
PageBuilder newPageSameSize()
font/at— 활성 폰트/크기와 커서 위치를 설정합니다.text/heading/paragraph— 텍스트, 특정 레벨의 제목, 또는 줄바꿈 처리된 문단을 출력합니다.space/horizontalRule/newline— 수직 간격, 가로줄, 줄바꿈.columns— 간격을 둔 다단 텍스트.inline/inlineBold/inlineItalic/inlineColor— 인라인 텍스트 런.footnote— 참조 표시와 각주 텍스트.textInRect— 정렬 코드(0=왼쪽, 1=가운데, 2=오른쪽)와 함께 사각형 안에 배치되는 텍스트.newPageSameSize— 동일한 크기의 새 페이지를 시작합니다.
링크
PageBuilder linkUrl(String url)
PageBuilder linkPage(int page)
PageBuilder linkNamed(String destination)
PageBuilder linkJavascript(String script)
마지막 콘텐츠에 URL 링크, 내부 페이지 링크, 이름 있는 대상 링크, 또는 JavaScript 링크를 첨부합니다.
액션 & 필드 스크립트
PageBuilder onOpen(String script)
PageBuilder onClose(String script)
PageBuilder fieldKeystroke(String script)
PageBuilder fieldFormat(String script)
PageBuilder fieldValidate(String script)
PageBuilder fieldCalculate(String script)
페이지 열기/닫기 액션과 AcroForm 필드의 keystroke/format/validate/calculate 스크립트입니다.
텍스트 마크업
PageBuilder highlight(double r, double g, double b)
PageBuilder underline(double r, double g, double b)
PageBuilder strikeout(double r, double g, double b)
PageBuilder squiggly(double r, double g, double b)
RGB 색상으로 마지막 텍스트 위에 마크업 주석을 추가합니다.
주석 / 워터마크 / 스탬프
PageBuilder stickyNote(String value)
PageBuilder stickyNoteAt(double x, double y, String value)
PageBuilder watermark(String value)
PageBuilder watermarkConfidential()
PageBuilder watermarkDraft()
PageBuilder stamp(String typeName)
PageBuilder freetext(double x, double y, double w, double h, String value)
stickyNote/stickyNoteAt— 커서 위치 또는 명시적 위치의 스티커 메모.watermark/watermarkConfidential/watermarkDraft— 사용자 정의 또는 미리 설정된 워터마크.stamp— 이름 있는 고무 스탬프.freetext— 사각형 안의 자유 텍스트 주석.
이미지 & 바코드
PageBuilder image(Uint8List bytes, double x, double y, double w, double h)
PageBuilder imageArtifact(Uint8List bytes, double x, double y, double w, double h)
PageBuilder imageWithAlt(Uint8List bytes, double x, double y, double w, double h, String altText)
PageBuilder barcode1d(int barcodeType, String data, double x, double y, double w, double h)
PageBuilder barcodeQr(String data, double x, double y, double size)
image— 이미지를 배치합니다.imageArtifact— 비콘텐츠(아티팩트) 이미지를 배치합니다.imageWithAlt— 접근성을 위한 대체 텍스트와 함께 이미지를 배치합니다.barcode1d/barcodeQr— 페이지에 직접 1차원 바코드 또는 QR 코드를 그립니다.
벡터 그래픽
PageBuilder rect(double x, double y, double w, double h)
PageBuilder filledRect(double x, double y, double w, double h, double r, double g, double b)
PageBuilder line(double x1, double y1, double x2, double y2)
PageBuilder strokeRect(double x, double y, double w, double h, double width, double r, double g, double b)
PageBuilder strokeLine(double x1, double y1, double x2, double y2, double width, double r, double g, double b)
PageBuilder strokeRectDashed(double x, double y, double w, double h, double width, double r, double g, double b, List<double> dashArray, [double phase = 0])
PageBuilder strokeLineDashed(double x1, double y1, double x2, double y2, double width, double r, double g, double b, List<double> dashArray, [double phase = 0])
채워진 사각형/선과 외곽선 사각형/선으로, 대시 배열과 위상(phase)을 가진 대시 스트로크를 포함합니다.
폼 필드
PageBuilder textField(String name, double x, double y, double w, double h, [String? defaultValue])
PageBuilder checkbox(String name, double x, double y, double w, double h, bool checked)
PageBuilder comboBox(String name, double x, double y, double w, double h, List<String> options, int count, [String? selected])
PageBuilder radioGroup(String name, List<String> values, List<double> xs, List<double> ys, List<double> ws, List<double> hs, int count, [String? selected])
PageBuilder pushButton(String name, double x, double y, double w, double h, String caption)
PageBuilder signatureField(String name, double x, double y, double w, double h)
AcroForm 위젯을 추가합니다: 텍스트 필드, 체크박스, 콤보 박스, 라디오 그룹, 푸시 버튼, 서명 필드.
테이블
PageBuilder table(int nCols, List<double> widths, List<int> aligns, int nRows, List<String> cellStrings, bool hasHeader)
PageBuilder streamingTableBegin(List<String> headers, List<double> widths, List<int> aligns, bool repeatHeader)
PageBuilder streamingTableBeginV2(List<String> headers, List<double> widths, List<int> aligns, bool repeatHeader, {int mode = 0, int sampleRows = 0, double minColWidthPt = 0, double maxColWidthPt = 0, int maxRowspan = 1})
PageBuilder streamingTablePushRow(List<String> cells)
PageBuilder streamingTablePushRowV2(List<String> cells, List<int> rowspans)
PageBuilder streamingTableFlush()
PageBuilder streamingTableFinish()
PageBuilder streamingTableSetBatchSize(int batchSize)
int streamingTableBatchCount()
int streamingTablePendingRowCount()
table— 정적인 행 우선(row-major) 테이블을 버퍼링합니다.streamingTableBegin/streamingTableBeginV2— 스트리밍 테이블을 시작합니다(v2는 열 너비 모드, 샘플 행, 최소/최대 열 너비, rowspan을 추가합니다).streamingTablePushRow/streamingTablePushRowV2— 행을 추가합니다(v2는 셀별 rowspan 포함).streamingTableFlush/streamingTableFinish— 대기 중인 행을 플러시 / 테이블을 닫습니다.streamingTableSetBatchSize— 각 플러시 전에 버퍼링할 행 수.streamingTableBatchCount/streamingTablePendingRowCount— 플러시된 배치 수 / 대기 중인 행 수.
수명 주기
void done()
void close()
done— 버퍼링된 작업을 부모 빌더에 커밋합니다(핸들을 소비합니다).close— 페이지를 폐기하고 핸들을 해제합니다(멱등).
EmbeddedFont
DocumentBuilder.registerEmbeddedFont를 통해 임베드하기 위해 로드된 TTF/OTF 폰트입니다.
static EmbeddedFont fromFile(String path)
static EmbeddedFont fromBytes(Uint8List data, [String? name])
void close()
fromFile— 파일 경로에서 폰트를 로드합니다.fromBytes— 바이트에서 로드합니다.name은 기본적으로 폰트의 PostScript 이름이 됩니다.close— 네이티브 핸들을 해제합니다(멱등).
RenderedImage
PdfDocument.renderPage와 그 친구 메서드들이 반환하는 래스터화된 페이지 이미지입니다.
int get width
int get height
Uint8List get data
void save(String path)
void close()
width/height— 픽셀 단위의 이미지 크기.data— 인코딩된 이미지 바이트(예: PNG)로, Dart로 복사됩니다.save— 인코딩된 이미지를 경로에 씁니다.close— 네이티브 핸들을 해제합니다(멱등).
ElementList
PdfDocument.pageElements가 생성하는 페이지의 레이아웃 요소입니다.
int get count
Element operator [](int index)
List<Element> toList()
String toJson()
void close()
count— 요소 수.operator []— 인덱스 위치의 요소를 읽습니다.toList— 모든 요소를 리스트로.toJson— 전체 리스트를 JSON으로 직렬화합니다.close— 네이티브 핸들을 해제합니다(멱등).
BarcodeImage
생성된 1차원 바코드 또는 QR 코드입니다. DocumentEditor.addBarcodeToPage로 페이지에 스탬프하세요.
static BarcodeImage qr(String data, {int errorCorrection = 0, int sizePx = 256})
static BarcodeImage barcode(String data, int format, {int sizePx = 256})
String get data
int get format
double get confidence
Uint8List imagePng({int sizePx = 256})
String svg({int sizePx = 256})
void close()
qr— 오류 정정 레벨과 픽셀 크기로 QR 코드를 생성합니다.barcode— 지정한 형식 코드로 1차원 바코드를 생성합니다.data/format/confidence— 인코딩된 페이로드, 형식 코드, 디코드 신뢰도.imagePng/svg— PNG 바이트 또는 SVG 문자열로 인코딩합니다.close— 네이티브 핸들을 해제합니다(멱등).
OcrEngine
검출/인식 모델 파일을 기반으로 하는 OCR 엔진으로, PdfDocument.ocrExtractText에 전달됩니다.
static OcrEngine create(String detModelPath, String recModelPath, String dictPath)
void close()
create— 검출 모델, 인식 모델, 사전 파일 경로로부터 엔진을 생성합니다.close— 네이티브 핸들을 해제합니다(멱등).
Renderer
고정된 DPI/형식/품질로 구성된 재사용 가능한 페이지 렌더러입니다.
static Renderer create({int dpi = 150, int format = 0, int quality = 90, bool antiAlias = true})
void close()
create— 렌더러를 생성합니다(format0=PNG, 1=JPEG;quality1…100).close— 네이티브 핸들을 해제합니다(멱등).
Certificate
서명 자격 증명 / X.509 인증서로, 서명 진입점에서 사용됩니다.
static Certificate loadFromBytes(Uint8List bytes, String password)
static Certificate loadFromPem(String certPem, String keyPem)
Pointer<Void> get handle
String get subject
String get issuer
String get serial
CertificateValidity get validity
bool isValid()
void close()
loadFromBytes— 비밀번호와 함께 PKCS#12(.p12/.pfx) 버퍼에서 로드합니다.loadFromPem— PEM 인증서 + 개인 키 문자열에서 로드합니다.handle— 원시 네이티브 핸들(고급/인터롭 용도).subject/issuer/serial— 식별 이름(DN)과 일련번호.validity—CertificateValidity형태의 notBefore/notAfter 구간.isValid— 인증서가 현재 유효한지 여부.close— 네이티브 핸들을 해제합니다(멱등).
Timestamp
RFC 3161 타임스탬프 토큰입니다.
static Timestamp parse(Uint8List bytes)
Uint8List get token
Uint8List get messageImprint
int get time
String get serial
String get tsaName
String get policyOid
int get hashAlgorithm
bool verify()
void close()
parse— DER 인코딩된 TimeStampToken(또는 단독 TSTInfo)을 파싱합니다.token/messageImprint— 전체 토큰과 해시된 메시지 임프린트 바이트.time— 타임스탬프 시각(Unix epoch 초).serial/tsaName/policyOid/hashAlgorithm— 토큰 일련번호, TSA 이름, 정책 OID, 해시 알고리즘 코드.verify— 토큰을 암호학적으로 검증합니다.close— 네이티브 핸들을 해제합니다(멱등).
TsaClient
RFC 3161 TSA(타임스탬프 기관) 클라이언트입니다.
static TsaClient create(String url, {String username = '', String password = '', int timeout = 30, int hashAlgo = 0, bool useNonce = true, bool certReq = true})
Timestamp requestTimestamp(Uint8List data)
Timestamp requestTimestampHash(Uint8List hash, int hashAlgo)
void close()
create— 선택적 기본 인증과 요청 옵션으로 TSA URL용 클라이언트를 생성합니다.requestTimestamp— 원시 데이터에 대해 타임스탬프를 요청합니다(클라이언트가 해시합니다).requestTimestampHash— 미리 계산된 해시에 대해 타임스탬프를 요청합니다.close— 네이티브 핸들을 해제합니다(멱등).
SignatureInfo
PdfDocument.getSignature에서 얻는, PDF에 임베드된 디지털 서명에 대한 정보입니다.
SignatureInfo.fromHandle(Pointer<Void> handle)
Pointer<Void> get handle
String get signerName
String get signingReason
String get signingLocation
int get signingTime
Certificate get certificate
int get padesLevel
bool hasTimestamp()
Timestamp get timestamp
bool addTimestamp(Timestamp ts)
int verify()
int verifyDetached(Uint8List pdf)
void close()
fromHandle— 원시 네이티브 핸들을 채택합니다(고급/인터롭 용도).signerName/signingReason/signingLocation/signingTime— 서명자 메타데이터.certificate— 서명자의Certificate.padesLevel— PAdES 베이스라인 레벨 코드, PAdES가 아니면-1.hasTimestamp/timestamp— 임베드된 타임스탬프 존재 여부와Timestamp자체.addTimestamp— 이 서명에 타임스탬프를 첨부합니다.verify— 서명자 속성 암호 검사(1 유효 / 0 무효 / -1 알 수 없음).verifyDetached— 전체 PDF 바이트에 대해 종단 간(end-to-end) 검증합니다(1 유효 / 0 무효 / -1 알 수 없음).close— 네이티브 핸들을 해제합니다(멱등).
Dss
PdfDocument.getDss에서 얻는 문서 /DSS(문서 보안 저장소)입니다.
Dss.fromHandle(Pointer<Void> handle)
int get certCount
int get crlCount
int get ocspCount
int get vriCount
Uint8List getCert(int index)
Uint8List getCrl(int index)
Uint8List getOcsp(int index)
void close()
fromHandle— 원시 DSS 핸들을 채택합니다(고급/인터롭 용도).certCount/crlCount/ocspCount/vriCount— 인증서, CRL, OCSP 응답, VRI 항목의 개수.getCert/getCrl/getOcsp— 인덱스 위치의 인증서 / CRL / OCSP 응답의 DER 바이트.close— 네이티브 핸들을 해제합니다(멱등).
PdfAResults
PdfDocument.validatePdfA에서 얻는 PDF/A 검증 결과입니다.
bool isCompliant()
List<String> errors()
List<String> warnings()
void close()
isCompliant— 문서가 PDF/A를 준수하는지 여부.errors/warnings— 검증 오류 및 경고 메시지.close— 네이티브 핸들을 해제합니다(멱등).
UaResults
PdfDocument.validatePdfUa에서 얻는 PDF/UA 접근성 검증 결과입니다.
bool isAccessible()
List<String> errors()
List<String> warnings()
UaStats uaStats()
void close()
isAccessible— 문서가 PDF/UA 접근 가능한지 여부.errors/warnings— 접근성 오류 및 경고 메시지.uaStats— 검증 중 수집된 요소 통계.close— 네이티브 핸들을 해제합니다(멱등).
PdfXResults
PdfDocument.validatePdfX에서 얻는 PDF/X 검증 결과입니다.
bool isCompliant()
List<String> errors()
void close()
isCompliant— 문서가 PDF/X를 준수하는지 여부.errors— 검증 오류 메시지.close— 네이티브 핸들을 해제합니다(멱등).
최상위 함수
이 라이브러리 수준 함수들은 pdf_oxide 네임스페이스에 있습니다.
병합 & 타임스탬프
Uint8List pdfMerge(List<String> paths)
Uint8List addTimestamp(Uint8List pdf, int sigIndex, String tsaUrl)
pdfMerge— 지정한 경로의 PDF들을 (순서대로) 하나의 PDF로 병합합니다. 그 바이트를 반환합니다.addTimestamp— TSA에 접속하여 서명에 RFC 3161 타임스탬프를 적용합니다. 타임스탬프가 적용된 PDF 바이트를 반환합니다.
서명
Uint8List signBytes(Uint8List pdf, Certificate cert, {String reason = '', String location = ''})
Uint8List signBytesPades(Uint8List pdf, Certificate cert, int level, {String? tsaUrl, String reason = '', String location = '', List<Uint8List> certs = const [], List<Uint8List> crls = const [], List<Uint8List> ocsps = const []})
Uint8List signBytesPadesOpts(Uint8List pdf, Certificate cert, int level, {String? tsaUrl, String reason = '', String location = '', List<Uint8List> certs = const [], List<Uint8List> crls = const [], List<Uint8List> ocsps = const []})
signBytes— 인증서로 원시 PDF 바이트에 서명합니다. 서명된 바이트를 반환합니다.signBytesPades— PAdES 베이스라인 레벨로 서명합니다(0=B-B, 1=B-T, 2=B-LT).tsaUrl은 레벨 ≥ 1에서 필수이며certs/crls/ocsps는 B-LT 폐기(revocation) 자료를 담습니다.signBytesPadesOpts— 동작이 동일한signBytesPades의 구조체 옵션 변형입니다.
로깅
void setLogLevel(int level)
int getLogLevel()
전역 라이브러리 로그 레벨을 설정/조회합니다(0=Off, 1=Error, 2=Warn, 3=Info, 4=Debug, 5=Trace).
암호화 / FIPS
String cryptoActiveProvider()
String cryptoCbom()
String cryptoInventory()
String cryptoPolicy()
int cryptoFipsAvailable()
int cryptoUseFips()
int cryptoSetPolicy(String spec)
cryptoActiveProvider— 활성 암호화 공급자 이름.cryptoCbom— 암호화 자재 명세서(CBOM)를 JSON으로.cryptoInventory— 암호화 인벤토리를 JSON으로.cryptoPolicy— 활성 암호화 정책을 JSON으로.cryptoFipsAvailable— FIPS 검증 공급자를 사용할 수 있는지 여부(0이 아니면 가능).cryptoUseFips— FIPS 검증 공급자로 전환합니다. 상태를 반환합니다.cryptoSetPolicy— 사양 문자열에서 암호화 정책을 설정합니다. 상태를 반환합니다.
모델 & 전역 설정
String modelManifest()
int prefetchAvailable()
String prefetchModels(String languagesCsv)
int setMaxOpsPerStream(int limit)
int setPreserveUnmappedGlyphs(int preserve)
modelManifest— 번들된 모델 매니페스트를 JSON으로.prefetchAvailable— 이 빌드에서 모델 프리페치를 사용할 수 있는지 여부.prefetchModels— 쉼표로 구분된 언어에 대해 OCR/레이아웃 모델을 프리페치합니다. JSON 보고서를 반환합니다.setMaxOpsPerStream— 콘텐츠 스트림당 전역 연산자 제한을 설정합니다. 이전 값을 반환합니다.setPreserveUnmappedGlyphs— 매핑되지 않은 글리프의 보존을 토글합니다. 이전 값을 반환합니다.
에러 처리
PdfOxideError
성공이 아닌 모든 C-ABI 에러 코드는 PdfOxideError로 던져집니다.
class PdfOxideError implements Exception {
final int code; // C-ABI error code
final String op; // the operation that failed
}
close() 이후에 핸들의 메서드를 호출하면 Dart의 StateError가 발생합니다. 잘못된 폰트 데이터로 EmbeddedFont.fromBytes를 호출하거나, 유효하지 않은 PKCS#12로 Certificate.loadFromBytes를 호출하거나, 존재하지 않는 파일로 PdfDocument.open을 호출하면 모두 PdfOxideError를 일으킵니다.
import 'package:pdf_oxide/pdf_oxide.dart';
void main() {
try {
final doc = PdfDocument.open('input.pdf');
print(doc.extractText(0));
doc.close();
} on PdfOxideError catch (e) {
print('PDF error: $e'); // PdfOxideError: <op> failed (error code <code>)
}
}
값 타입
추출 및 검사 메서드가 반환하는 단순 데이터 클래스입니다.
PdfVersion
| 필드 | 타입 | 설명 |
|---|---|---|
major |
int |
주(major) 버전 |
minor |
int |
부(minor) 버전 |
Bbox
PDF 사용자 공간 포인트 단위의 축 정렬 경계 상자(bounding box)입니다.
| 필드 | 타입 | 설명 |
|---|---|---|
x, y |
double |
좌하단 원점 |
width, height |
double |
상자 크기 |
Char
| 필드 | 타입 | 설명 |
|---|---|---|
character |
int |
유니코드 코드포인트 |
bbox |
Bbox |
글리프 경계 상자 |
fontName |
String |
PostScript 폰트 이름 |
fontSize |
double |
포인트 단위 폰트 크기 |
Word
| 필드 | 타입 | 설명 |
|---|---|---|
text |
String |
단어 텍스트 |
bbox |
Bbox |
경계 상자 |
fontName |
String |
폰트 이름 |
fontSize |
double |
폰트 크기 |
bold |
bool |
굵게 여부 |
TextLine
| 필드 | 타입 | 설명 |
|---|---|---|
text |
String |
줄 텍스트 |
bbox |
Bbox |
경계 상자 |
wordCount |
int |
단어 수 |
Table
| 멤버 | 타입 | 설명 |
|---|---|---|
rowCount |
int |
행 수 |
colCount |
int |
열 수 |
hasHeader |
bool |
머리글 행 존재 여부 |
cell(int row, int col) |
String |
0부터 시작하는 셀의 텍스트 |
Font
| 필드 | 타입 | 설명 |
|---|---|---|
name |
String |
폰트 이름 |
type |
String |
폰트 타입 |
encoding |
String |
인코딩 |
embedded |
bool |
임베드 여부 |
subset |
bool |
서브셋 여부 |
Image
| 필드 | 타입 | 설명 |
|---|---|---|
width, height |
int |
픽셀 크기 |
bitsPerComponent |
int |
컴포넌트당 비트 수 |
format |
String |
이미지 형식 |
colorspace |
String |
색 공간 |
data |
Uint8List |
원시 이미지 바이트 |
Annotation
| 필드 | 타입 | 설명 |
|---|---|---|
type |
String |
주석 타입 |
subtype |
String |
주석 서브타입 |
content |
String |
텍스트 콘텐츠 |
author |
String |
작성자 |
rect |
Bbox |
위치 |
borderWidth |
double |
테두리 너비 |
Path
| 필드 | 타입 | 설명 |
|---|---|---|
bbox |
Bbox |
경계 상자 |
strokeWidth |
double |
스트로크 너비 |
hasStroke |
bool |
외곽선 여부 |
hasFill |
bool |
채움 여부 |
operationCount |
int |
경로 연산 수 |
SearchResult
| 필드 | 타입 | 설명 |
|---|---|---|
text |
String |
일치한 텍스트 |
page |
int |
0부터 시작하는 페이지 인덱스 |
bbox |
Bbox |
일치 경계 상자 |
FormField
| 필드 | 타입 | 설명 |
|---|---|---|
name |
String |
완전 정규화된 필드 이름 |
value |
String |
현재 값 |
type |
String |
필드 타입(Tx, Btn, Ch, Sig) |
readonly |
bool |
읽기 전용 여부 |
required |
bool |
필수 여부 |
QuadPoint
하이라이트 주석의 quad(네 모서리 점): x1, y1, x2, y2, x3, y3, x4, y4(double).
AnnotationDetails
| 필드 | 타입 | 설명 |
|---|---|---|
type, subtype, content |
String |
주석 타입/서브타입과 내용 |
rect |
Bbox |
위치 |
color |
int |
패킹된 ARGB 색상 |
creationDate, modificationDate |
int |
Unix epoch 초(없으면 0) |
hidden, markedDeleted, printable, readOnly |
bool |
주석 플래그 |
linkUri |
String |
링크 대상 URI(없으면 빈 문자열) |
iconName |
String |
텍스트 주석 아이콘 이름(없으면 빈 문자열) |
quadPoints |
List<QuadPoint> |
하이라이트 quad point(없으면 빈 리스트) |
CertificateValidity
| 필드 | 타입 | 설명 |
|---|---|---|
notBefore |
int |
유효 시작 시각(Unix epoch 초) |
notAfter |
int |
유효 종료 시각(Unix epoch 초) |
UaStats
| 필드 | 타입 | 설명 |
|---|---|---|
structElements |
int |
구조 요소 |
images |
int |
이미지 |
tables |
int |
테이블 |
forms |
int |
폼 필드 |
annotations |
int |
주석 |
pages |
int |
페이지 |
Element
| 필드 | 타입 | 설명 |
|---|---|---|
type |
String |
요소 타입(예: Text, Image, Table) |
text |
String |
텍스트 콘텐츠(빈 문자열일 수 있음) |
rect |
Bbox |
경계 상자 |
전체 예제
import 'dart:io';
import 'package:pdf_oxide/pdf_oxide.dart';
void main() {
// --- Creation ---
final pdf = Pdf.fromMarkdown('# Report\n\nGenerated by PDF Oxide.');
pdf.save('report.pdf');
pdf.close();
// --- Builder ---
final db = DocumentBuilder.create()..setTitle('Invoice');
final page = db.letterPage();
page
.font('Helvetica', 14)
.heading(1, 'Invoice')
.paragraph('Thank you for your business.')
.done();
File('invoice.pdf').writeAsBytesSync(db.build());
db.close();
// --- Extraction ---
final doc = PdfDocument.open('report.pdf');
print('Pages: ${doc.pageCount}');
for (var i = 0; i < doc.pageCount; i++) {
print('Page $i: ${doc.extractText(i).length} chars');
}
for (final word in doc.extractWords(0)) {
print('${word.text} @ ${word.bbox}');
}
// --- Search ---
for (final hit in doc.searchAll('PDF Oxide', false)) {
print('Found "${hit.text}" on page ${hit.page}');
}
// --- Rendering ---
final img = doc.renderPage(0);
img.save('page0.png');
img.close();
doc.close();
// --- Editing ---
final ed = DocumentEditor.open('report.pdf');
ed.rotateAllPages(90);
ed.setProducer('PDF Oxide');
ed.save('rotated.pdf');
ed.close();
}
Other Language Bindings
PDF Oxide는 모든 주요 생태계를 위한 네이티브 바인딩을 제공합니다: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, R, Julia, Zig, Scala, Clojure, Objective-C, Elixir
다음 단계
- 타입 & 열거형 — 모든 공유 타입과 열거형
- Page API 레퍼런스 — 바인딩 간 일관된 페이지 단위 순회
- Dart 시작하기 — 튜토리얼