Dart API 参考

PDF Oxide 提供地道的 Dart/Flutter 绑定，基于原生 C ABI 用 dart:ffi 构建。该包在运行时加载预编译的 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 — 序列化为 JSON 的结构化页面内容（spans、布局）。
• 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 points）。
• 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（format 0=PNG，1=JPEG）。
• renderPageZoom — 以缩放系数渲染。
• renderPageThumbnail — 渲染一个适配 size 像素的缩略图。
• renderPageWithOptions — 完整的 RenderOptions 能力面（dpi、背景、注释、JPEG 质量）。
• renderPageWithOptionsEx — 增加了通过 excludedLayers 抑制具名 OCG 图层的能力。
• renderPageRegion — 渲染一个矩形区域。
• renderPageFit — 在保持宽高比的前提下渲染以适配 width×height。
• renderPageRaw — 按 dpi 渲染为原始的预乘 RGBA8888 缓冲区。
• estimateRenderTime — 估算某页的渲染时间（毫秒）。

页面几何与元素

double pageWidth(int pageIndex)
double pageHeight(int pageIndex)
int pageRotation(int pageIndex)
ElementList pageElements(int pageIndex)
Page page(int index)

• pageWidth / pageHeight — 以 PDF 点为单位的页面尺寸。
• pageRotation — 以度为单位的页面旋转角。
• 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 — 导出表单数据（formatType 0=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

为简单的构建/保存流程而生产（或加载）的 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 — 从 HTML + CSS 构建，并带有 families/fonts 并行的字体级联。

方法

int get pageCount
void save(String path)
Uint8List toBytes()
void close()

• pageCount — 通过 pdf_get_page_count 入口获取的页数。
• save — 保存到文件。
• toBytes — 以字节形式返回的 PDF 内容。
• close — 释放原生句柄（幂等）。

---

DocumentEditor

为就地编辑而打开的 PDF：页面操作、元数据、表单、涂黑、扁平化、合并以及加密保存。

构造函数

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。

涂黑与抹除

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 / 嵌入文件；返回被移除的构件数。

扁平化

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（level 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 文档的流式构建器。

创建

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)

以 PageBuilder 形式打开一个 A4、US Letter 或自定义尺寸的页面。

构建 / 保存

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 字段的击键/格式/校验/计算脚本。

文本标注

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 — 直接在页面上绘制一维条码或 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])

填充和描边的矩形与线条，包括带虚线数组和相位的虚线描边。

表单字段

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 — 缓冲一个静态的、按行存储的表格。
• streamingTableBegin / streamingTableBeginV2 — 开始一个流式表格（v2 增加了列宽模式、采样行、最小/最大列宽和跨行）。
• streamingTablePushRow / streamingTablePushRowV2 — 推入一行（v2 带逐单元格的跨行）。
• 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

生成的一维条码或 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 — 以指定格式码生成一维条码。
• 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 — 创建一个渲染器（format 0=PNG，1=JPEG；quality 1…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 — 可分辨名称和序列号。
• 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 — 完整令牌和经哈希的 message-imprint 字节。
• time — 时间戳时间（Unix 纪元秒）。
• serial / tsaName / policyOid / hashAlgorithm — 令牌序列号、TSA 名称、policy 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 创建客户端，可带可选的 basic-auth 和请求选项。
• 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 字节做端到端校验（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）；level ≥ 1 时需要 tsaUrl，certs/crls/ocsps 携带 B-LT 吊销材料。
• 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 — 以 JSON 表示的密码学物料清单（CBOM）。
• cryptoInventory — 以 JSON 表示的密码学清单。
• cryptoPolicy — 以 JSON 表示的当前活跃密码学策略。
• cryptoFipsAvailable — 是否有经 FIPS 验证的提供方可用（非零 = 是）。
• 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 遇到无效字体数据、Certificate.loadFromBytes 遇到无效 PKCS#12，以及 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	主版本号
minor	int	次版本号

Bbox

PDF 用户空间点中的一个轴对齐边界框。

字段	类型	说明
x, y	double	左下角原点
width, height	double	框的尺寸

Char

字段	类型	说明
character	int	Unicode 码点
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 纪元秒（缺失时为 0）
hidden, markedDeleted, printable, readOnly	bool	注释标志位
linkUri	String	链接目标 URI（否则为空）
iconName	String	文本注释图标名（否则为空）
quadPoints	List<QuadPoint>	高亮 quad points（否则为空）

CertificateValidity

字段	类型	说明
notBefore	int	生效起始时间（Unix 纪元秒）
notAfter	int	有效截止时间（Unix 纪元秒）

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 快速上手 — 教程