Skip to content
PDF Oxide

Referência da API Dart

O PDF Oxide oferece bindings idiomáticos para Dart/Flutter construídos com dart:ffi sobre a C ABI nativa. O pacote carrega a biblioteca pré-compilada libpdf_oxide.{so,dylib,dll} em tempo de execução e expõe toda a superfície — extração, edição, criação, renderização, formulários, OCR, códigos de barras, assinaturas digitais e validação de conformidade.

dart pub add pdf_oxide

import 'package:pdf_oxide/pdf_oxide.dart';

Os handles nativos são liberados automaticamente por um NativeFinalizer, mas toda classe que detém um handle também expõe um close() idempotente que você deve chamar ao terminar (ou use addTearDown/try/finally). Os códigos de erro da C ABI são lançados como PdfOxideError. Todos os índices de página começam em zero.

Para outras linguagens, consulte a Referência da API Python, a Referência da API JavaScript (Node.js), a Referência da API JavaScript (WASM), a Referência da API Rust e Tipos e Enums.

PdfDocument

A classe principal para abrir, extrair, renderizar, validar e inspecionar um PDF.

Construtores / Factories

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 — abre um PDF a partir de um caminho no sistema de arquivos.
  • openFromBytes — abre um PDF a partir de bytes em memória.
  • openWithPassword — abre um PDF protegido por senha.
  • openFromDocxBytes / openFromPptxBytes / openFromXlsxBytes — abre um documento diretamente de bytes DOCX/PPTX/XLSX.

Informações do Documento

int get pageCount
PdfVersion get version
bool isEncrypted()
bool hasStructureTree()
bool authenticate(String password)
  • pageCount — número de páginas.
  • version — versão do PDF como um PdfVersion(major, minor).
  • isEncrypted — se o documento está criptografado.
  • hasStructureTree — se este é um Tagged PDF com uma árvore de estrutura.
  • authenticate — autentica um PDF criptografado; retorna true em caso de sucesso e false para uma senha incorreta.

Texto e Conversão

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 — texto extraído puro de uma única página.
  • toPlainText / toMarkdown / toHtml — converte uma única página para texto puro, Markdown ou HTML.
  • extractStructuredJson — conteúdo estruturado da página (spans, layout) serializado em JSON.
  • toMarkdownAll / toHtmlAll / toPlainTextAll — converte o documento inteiro.

Extração de Elementos

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 — geometria por glifo, por palavra e por linha.
  • extractTables — tabelas detectadas com células lidas sob demanda (Table.cell).
  • embeddedFonts / embeddedFontsJson / embeddedFontSizes — metadados das fontes incorporadas de uma página.
  • embeddedImages — imagens incorporadas com os bytes brutos.
  • pageAnnotations — anotações de uma página.
  • pageAnnotationDetails — atributos estendidos de anotação (flags, datas, cor, URIs de link, nomes de ícones, quad points).
  • annotationsToJson — anotações serializadas em JSON.
  • extractPaths — elementos de caminho vetorial (gráficos).

Extração por Retângulo

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)

Extrai texto, palavras, linhas, tabelas ou imagens restritos a um retângulo (em pontos do espaço de usuário do PDF) em uma página.

Extração e Classificação Automáticas

String extractTextAuto(int page)
String extractPageAuto(int page, [String optionsJson = ''])
String extractAllText()
String classifyPage(int page)
String classifyDocument()
  • extractTextAuto — extração nativa + OCR de imagem conforme necessário para uma página.
  • extractPageAuto — extração automática de uma única página com opções JSON opcionais.
  • extractAllText — o texto de todas as páginas em uma única string.
  • classifyPage / classifyDocument — classificação de página/documento em JSON (digitalizado, digital, híbrido, etc.).

Busca

List<SearchResult> search(int page, String term, bool caseSensitive)
List<SearchResult> searchAll(String term, bool caseSensitive)
String searchResultsToJson(int page, String term, bool caseSensitive)

Busca em uma única página, no documento inteiro, ou serializa os resultados de uma página em JSON.

Renderização

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 — renderiza uma página para um RenderedImage (format 0=PNG, 1=JPEG).
  • renderPageZoom — renderiza com um fator de zoom.
  • renderPageThumbnail — renderiza uma miniatura ajustada a size pixels.
  • renderPageWithOptions — a superfície completa de RenderOptions (dpi, fundo, anotações, qualidade JPEG).
  • renderPageWithOptionsEx — adiciona a supressão de camadas OCG nomeadas via excludedLayers.
  • renderPageRegion — renderiza uma região retangular.
  • renderPageFit — renderiza para caber dentro de width×height preservando a proporção.
  • renderPageRaw — renderiza para um buffer RGBA8888 bruto pré-multiplicado em dpi.
  • estimateRenderTime — estima o tempo de renderização (ms) de uma página.

Geometria e Elementos da Página

double pageWidth(int pageIndex)
double pageHeight(int pageIndex)
int pageRotation(int pageIndex)
ElementList pageElements(int pageIndex)
Page page(int index)
  • pageWidth / pageHeight — dimensões da página em pontos PDF.
  • pageRotation — rotação da página em graus.
  • pageElements — elementos de layout de uma página como um ElementList.
  • page — uma visão Page leve para extração encadeada por página.

OCR

bool pageNeedsOcr(int pageIndex)
String ocrExtractText(int pageIndex, [OcrEngine? engine])
  • pageNeedsOcr — se uma página é digitalizada/híbrida e precisa de OCR.
  • ocrExtractText — extrai texto via OCR; engine pode ser null para apenas extração nativa.

Validação e Conversão de Conformidade

PdfAResults validatePdfA(int level)
UaResults validatePdfUa(int level)
PdfXResults validatePdfX(int level)
bool convertToPdfA(int level)
  • validatePdfA / validatePdfUa / validatePdfX — valida contra PDF/A, acessibilidade PDF/UA ou PDF/X.
  • convertToPdfA — converte este documento in-place para PDF/A no nível indicado.

Exportação para Office

Uint8List toDocx()
Uint8List toPptx()
Uint8List toXlsx()
Uint8List sourceBytes()
  • toDocx / toPptx / toXlsx — exporta o documento para bytes DOCX/PPTX/XLSX.
  • sourceBytes — os bytes de origem a partir dos quais este documento foi carregado.

Remoção de Cabeçalho / Rodapé / Artefatos

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 — apaga o cabeçalho, o rodapé ou os artefatos marcados em uma página; retorna a quantidade de itens apagados.
  • removeHeaders / removeFooters / removeArtifacts — remove elementos repetitivos do documento inteiro usando um limiar de detecção.

Formulários

List<FormField> getFormFields()
Uint8List exportFormDataToBytes([int formatType = 0])
void importFormData(String dataPath)
bool importFormFromFile(String filename)
  • getFormFields — campos interativos de AcroForm.
  • exportFormDataToBytes — exporta os dados do formulário (formatType 0=FDF, 1=XFDF, 2=JSON).
  • importFormData — importa dados de formulário a partir de um caminho de arquivo FDF/XFDF/JSON.
  • importFormFromFile — importa valores de campos de um arquivo; retorna se algo foi importado.

Estrutura e Metadados do Documento

String getOutline()
String getPageLabels()
String getXmpMetadata()
bool hasXfa()
String planSplitByBookmarks([String optionsJson = ''])
  • getOutline — o sumário do documento (marcadores) em JSON.
  • getPageLabels — os intervalos de rótulos de página em JSON.
  • getXmpMetadata — os metadados XMP (XML), se presentes.
  • hasXfa — se o documento contém um formulário XFA.
  • planSplitByBookmarks — produz um plano JSON de divisão por marcadores.

Assinaturas Digitais

int sign(Certificate certificate, {String reason = '', String location = ''})
int getSignatureCount()
SignatureInfo getSignature(int index)
int verifyAllSignatures()
bool hasTimestamp()
Dss getDss()
  • sign — assina digitalmente o documento com um Certificate.
  • getSignatureCount — número de assinaturas presentes.
  • getSignature — o SignatureInfo em um índice.
  • verifyAllSignatures — verifica todas as assinaturas (status agregado).
  • hasTimestamp — se alguma assinatura carrega um timestamp.
  • getDss — o document security store (Dss).

Ciclo de Vida

void close()

Libera o handle nativo imediatamente (idempotente).

Page

Uma visão leve, com índice baseado em zero, de uma única página retornada por PdfDocument.page(index). Mantém uma referência forte ao seu documento e delega aos métodos por página do documento.

Membro Tipo Descrição
index int Índice da página baseado em zero 
String text()
String markdown()
String html()
String plainText()

Texto extraído, Markdown, HTML ou texto puro desta página.

Pdf

Um PDF produzido (ou carregado) para o fluxo simples de builder/save.

Factories

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 — cria um PDF a partir de Markdown, HTML ou texto puro.
  • fromImage / fromImageBytes — envolve um arquivo de imagem ou bytes de imagem em um PDF de página única.
  • fromHtmlCss — constrói a partir de HTML + CSS com uma fonte incorporada opcional.
  • fromHtmlCssWithFonts — constrói a partir de HTML + CSS com uma cascata de fontes paralela families/fonts.

Métodos

int get pageCount
void save(String path)
Uint8List toBytes()
void close()
  • pageCount — contagem de páginas via o ponto de entrada pdf_get_page_count.
  • save — salva em um arquivo.
  • toBytes — o conteúdo do PDF como bytes.
  • close — libera o handle nativo (idempotente).

DocumentEditor

Um PDF aberto para edição in-place: operações de página, metadados, formulários, redação, flatten, mesclagem e gravações criptografadas.

Construtores

static DocumentEditor open(String path)
static DocumentEditor openFromBytes(Uint8List data)

Informações e Metadados do Documento

int get pageCount
PdfVersion get version
bool isModified()
String getSourcePath()
String getProducer()
void setProducer(String value)
String getCreationDate()
void setCreationDate(String dateStr)
  • isModified — se há modificações não salvas.
  • getSourcePath — o caminho a partir do qual o editor foi aberto.
  • getProducer / setProducer — o campo de metadados Producer.
  • getCreationDate / setCreationDate — o campo de metadados CreationDate.

Operações de Página

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 — exclui ou reordena páginas.
  • rotatePageBy — rotação aditiva; rotateAllPages — rotação relativa de todas as páginas; setPageRotation — absoluta; getPageRotation — a atual.
  • cropMargins — recorta as margens de todas as páginas.
  • getPageCropBox / setPageCropBox / getPageMediaBox / setPageMediaBox — lê/escreve a CropBox/MediaBox.

Redação e Apagamento

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 — aplica as redações enfileiradas.
  • eraseRegion / eraseRegions / clearEraseRegions — apaga um, vários, ou limpa os retângulos de apagamento pendentes.
  • isPageMarkedForRedaction / unmarkPageForRedaction — consulta/limpa a marca de redação de uma página.
  • redactionAdd — enfileira um retângulo de redação com uma cor de preenchimento da sobreposição.
  • redactionCount — regiões de redação enfileiradas para uma página.
  • redactionApply — aplica todas as redações de forma destrutiva; retorna a quantidade de glifos removidos.
  • redactionScrubMetadata — remove metadados / JavaScript / arquivos incorporados; retorna a quantidade de construções removidas.

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 — achata todos os campos de formulário, ou os de uma página.
  • flattenAnnotations / flattenAllAnnotations — achata as anotações de uma página ou do documento inteiro.
  • flattenWarningsCount / flattenWarning — avisos da última gravação com flatten.
  • isPageMarkedForFlatten / unmarkPageForFlatten — consulta/limpa a marca de flatten de uma página.

Formulários

void setFormFieldValue(String name, String value)
void importFdfBytes(Uint8List data)
void importXfdfBytes(Uint8List data)
  • setFormFieldValue — define o valor de um campo pelo nome.
  • importFdfBytes / importXfdfBytes — importa valores de AcroForm a partir de bytes FDF/XFDF.

Mesclar / Converter / Incorporar / Extrair

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 — anexa páginas de um PDF em disco ou em memória.
  • convertToPdfA — converte in-place para PDF/A (nível 0=A1b … 7=A3u).
  • embedFile — anexa um arquivo nomeado.
  • extractPagesToBytes — extrai um subconjunto de páginas para um novo PDF em memória.

Códigos de Barras

void addBarcodeToPage(int pageIndex, BarcodeImage barcode, double x, double y, double width, double height)

Carimba um BarcodeImage gerado em uma página no retângulo indicado.

Salvando

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 — salva em um arquivo ou em um buffer de bytes.
  • saveToBytesWithOptions — salva com opções explícitas de compressão / garbage-collect / linearização.
  • saveEncrypted / saveEncryptedToBytes — gravação criptografada com AES-256 em arquivo ou bytes.
  • close — libera o handle nativo (idempotente).

DocumentBuilder

Um builder fluente para montar um documento PDF totalmente novo.

Criação

static DocumentBuilder create()

Metadados (fluente)

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 — metadados do documento.
  • onOpen — JavaScript de abertura do documento.
  • language — idioma do documento.
  • taggedPdfUa1 — habilita o modo tagged PDF/UA-1.
  • roleMap — mapeia um tipo de estrutura personalizado para um tipo PDF padrão.
  • registerEmbeddedFont — registra uma fonte sob um nome (consome o EmbeddedFont em caso de sucesso).

Páginas

PageBuilder a4Page()
PageBuilder letterPage()
PageBuilder page(double width, double height)

Abre uma página A4, US Letter ou de tamanho personalizado como um PageBuilder.

Build / Save

Uint8List build()
void save(String path)
void saveEncrypted(String path, String userPassword, String ownerPassword)
Uint8List toBytesEncrypted(String userPassword, String ownerPassword)
void close()
  • build — constrói o PDF e retorna seus bytes.
  • save — constrói e salva em um caminho.
  • saveEncrypted / toBytesEncrypted — build criptografado com AES-256 para arquivo ou bytes.
  • close — libera o handle nativo (idempotente).

PageBuilder

Um builder fluente para uma única página, retornado por DocumentBuilder.page / letterPage / a4Page. Toda operação retorna this para encadeamento. Chame done() para confirmar a página ou close() para descartá-la.

Texto e Layout

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 — define a fonte/tamanho ativos e a posição do cursor.
  • text / heading / paragraph — emite texto, um título em um nível, ou um parágrafo com quebra de linha.
  • space / horizontalRule / newline — espaçamento vertical, uma régua, uma quebra de linha.
  • columns — texto em múltiplas colunas com um espaçamento.
  • inline / inlineBold / inlineItalic / inlineColor — trechos de texto inline.
  • footnote — uma marca de referência mais o texto da nota.
  • textInRect — texto disposto dentro de um retângulo com um código de alinhamento (0=Esquerda, 1=Centro, 2=Direita).
  • newPageSameSize — inicia uma nova página do mesmo tamanho.
PageBuilder linkUrl(String url)
PageBuilder linkPage(int page)
PageBuilder linkNamed(String destination)
PageBuilder linkJavascript(String script)

Anexa um link de URL, um link de página interno, um link de destino nomeado ou um link JavaScript ao último conteúdo.

Ações e Scripts de Campo

PageBuilder onOpen(String script)
PageBuilder onClose(String script)
PageBuilder fieldKeystroke(String script)
PageBuilder fieldFormat(String script)
PageBuilder fieldValidate(String script)
PageBuilder fieldCalculate(String script)

Ações de abertura/fechamento de página e scripts de keystroke/format/validate/calculate de campos AcroForm.

Marcação de Texto

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)

Anotações de marcação sobre o último texto em uma cor RGB.

Anotações / Marca d’água / Carimbo

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 — uma nota adesiva no cursor ou em uma posição explícita.
  • watermark / watermarkConfidential / watermarkDraft — marcas d’água personalizadas ou predefinidas.
  • stamp — um carimbo de borracha nomeado.
  • freetext — uma anotação de texto livre em um retângulo.

Imagens e Códigos de Barras

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 — posiciona uma imagem; imageArtifact — posiciona uma imagem que não é conteúdo (artefato); imageWithAlt — posiciona uma imagem com texto alternativo para acessibilidade.
  • barcode1d / barcodeQr — desenha um código de barras 1-D ou um código QR diretamente na página.

Gráficos Vetoriais

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])

Retângulos e linhas preenchidos e traçados, incluindo traços tracejados com um dash array e fase.

Campos de Formulário

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)

Adiciona widgets AcroForm: campos de texto, checkboxes, combo boxes, grupos de radio, push buttons e campos de assinatura.

Tabelas

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 — armazena em buffer uma tabela estática, em ordem de linhas.
  • streamingTableBegin / streamingTableBeginV2 — inicia uma tabela em streaming (a v2 adiciona modo de largura de coluna, linhas de amostra, larguras mínima/máxima de coluna e rowspan).
  • streamingTablePushRow / streamingTablePushRowV2 — adiciona uma linha (a v2 com rowspans por célula).
  • streamingTableFlush / streamingTableFinish — descarrega as linhas pendentes / encerra a tabela.
  • streamingTableSetBatchSize — linhas em buffer antes de cada flush.
  • streamingTableBatchCount / streamingTablePendingRowCount — lotes descarregados / linhas pendentes.

Ciclo de Vida

void done()
void close()
  • done — confirma as operações em buffer no builder pai (consome o handle).
  • close — descarta a página e libera o handle (idempotente).

EmbeddedFont

Uma fonte TTF/OTF carregada para incorporação via DocumentBuilder.registerEmbeddedFont.

static EmbeddedFont fromFile(String path)
static EmbeddedFont fromBytes(Uint8List data, [String? name])
void close()
  • fromFile — carrega uma fonte a partir de um caminho de arquivo.
  • fromBytes — carrega a partir de bytes; name assume por padrão o nome PostScript da fonte.
  • close — libera o handle nativo (idempotente).

RenderedImage

Uma imagem de página rasterizada retornada por PdfDocument.renderPage e similares.

int get width
int get height
Uint8List get data
void save(String path)
void close()
  • width / height — dimensões da imagem em pixels.
  • data — bytes da imagem codificada (por exemplo, PNG), copiados para o Dart.
  • save — grava a imagem codificada em um caminho.
  • close — libera o handle nativo (idempotente).

ElementList

Os elementos de layout de uma página, produzidos por PdfDocument.pageElements.

int get count
Element operator [](int index)
List<Element> toList()
String toJson()
void close()
  • count — número de elementos.
  • operator [] — lê o elemento em um índice.
  • toList — todos os elementos como uma lista.
  • toJson — a lista inteira serializada em JSON.
  • close — libera o handle nativo (idempotente).

BarcodeImage

Um código de barras 1-D ou código QR gerado. Carimbe em uma página com 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 — gera um código QR com um nível de correção de erros e tamanho em pixels.
  • barcode — gera um código de barras 1-D em um código de formato indicado.
  • data / format / confidence — o payload codificado, o código de formato e a confiança da decodificação.
  • imagePng / svg — codifica como bytes PNG ou uma string SVG.
  • close — libera o handle nativo (idempotente).

OcrEngine

Um mecanismo de OCR apoiado por arquivos de modelo de detecção/reconhecimento, passado para PdfDocument.ocrExtractText.

static OcrEngine create(String detModelPath, String recModelPath, String dictPath)
void close()
  • create — cria um mecanismo a partir dos caminhos do modelo de detecção, do modelo de reconhecimento e do arquivo de dicionário.
  • close — libera o handle nativo (idempotente).

Renderer

Um renderizador de página reutilizável configurado com DPI/formato/qualidade fixos.

static Renderer create({int dpi = 150, int format = 0, int quality = 90, bool antiAlias = true})
void close()
  • create — cria um renderizador (format 0=PNG, 1=JPEG; quality 1…100).
  • close — libera o handle nativo (idempotente).

Certificate

Credenciais de assinatura / um certificado X.509, usado pelos pontos de entrada de assinatura.

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 — carrega a partir de um buffer PKCS#12 (.p12/.pfx) com uma senha.
  • loadFromPem — carrega a partir de strings PEM de certificado + chave privada.
  • handle — o handle nativo bruto (uso avançado/interop).
  • subject / issuer / serial — os distinguished names e o número de série.
  • validity — a janela notBefore/notAfter como um CertificateValidity.
  • isValid — se o certificado é válido no momento.
  • close — libera o handle nativo (idempotente).

Timestamp

Um token de 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 — analisa um TimeStampToken codificado em DER (ou um TSTInfo nu).
  • token / messageImprint — o token completo e os bytes do message-imprint com hash.
  • time — o horário do timestamp (segundos da época Unix).
  • serial / tsaName / policyOid / hashAlgorithm — número de série do token, nome da TSA, OID de política e código do algoritmo de hash.
  • verify — verifica criptograficamente o token.
  • close — libera o handle nativo (idempotente).

TsaClient

Um cliente de TSA (autoridade de timestamp) RFC 3161.

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 — cria um cliente para uma URL de TSA com basic-auth opcional e opções de requisição.
  • requestTimestamp — solicita um timestamp sobre dados brutos (o cliente faz o hash deles).
  • requestTimestampHash — solicita um timestamp sobre um hash pré-calculado.
  • close — libera o handle nativo (idempotente).

SignatureInfo

Informações sobre uma assinatura digital incorporada em um PDF, de PdfDocument.getSignature.

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 — adota um handle nativo bruto (uso avançado/interop).
  • signerName / signingReason / signingLocation / signingTime — metadados do signatário.
  • certificate — o Certificate do signatário.
  • padesLevel — o código do nível baseline PAdES, ou -1 se não for PAdES.
  • hasTimestamp / timestamp — se existe um timestamp incorporado e o próprio Timestamp.
  • addTimestamp — anexa um timestamp a esta assinatura.
  • verify — verificação criptográfica dos atributos do signatário (1 válido / 0 inválido / -1 desconhecido).
  • verifyDetached — verifica de ponta a ponta contra os bytes completos do PDF (1 válido / 0 inválido / -1 desconhecido).
  • close — libera o handle nativo (idempotente).

Dss

Um /DSS de documento (document security store), de PdfDocument.getDss.

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 — adota um handle DSS bruto (uso avançado/interop).
  • certCount / crlCount / ocspCount / vriCount — contagens de certificados, CRLs, respostas OCSP e entradas VRI.
  • getCert / getCrl / getOcsp — os bytes DER do certificado / CRL / resposta OCSP em um índice.
  • close — libera o handle nativo (idempotente).

PdfAResults

Resultados de validação PDF/A de PdfDocument.validatePdfA.

bool isCompliant()
List<String> errors()
List<String> warnings()
void close()
  • isCompliant — se o documento é compatível com PDF/A.
  • errors / warnings — mensagens de erro e de aviso da validação.
  • close — libera o handle nativo (idempotente).

UaResults

Resultados de validação de acessibilidade PDF/UA de PdfDocument.validatePdfUa.

bool isAccessible()
List<String> errors()
List<String> warnings()
UaStats uaStats()
void close()
  • isAccessible — se o documento é acessível conforme PDF/UA.
  • errors / warnings — mensagens de erro e de aviso de acessibilidade.
  • uaStats — estatísticas de elementos coletadas durante a validação.
  • close — libera o handle nativo (idempotente).

PdfXResults

Resultados de validação PDF/X de PdfDocument.validatePdfX.

bool isCompliant()
List<String> errors()
void close()
  • isCompliant — se o documento é compatível com PDF/X.
  • errors — mensagens de erro da validação.
  • close — libera o handle nativo (idempotente).

Funções de Nível Superior

Estas funções de nível de biblioteca residem no namespace pdf_oxide.

Mesclar e Timestamp

Uint8List pdfMerge(List<String> paths)
Uint8List addTimestamp(Uint8List pdf, int sigIndex, String tsaUrl)
  • pdfMerge — mescla os PDFs nos caminhos indicados (em ordem) em um único PDF; retorna seus bytes.
  • addTimestamp — aplica um timestamp RFC 3161 a uma assinatura, contatando uma TSA; retorna os bytes do PDF com timestamp.

Assinatura

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 — assina bytes brutos de PDF com um certificado; retorna os bytes assinados.
  • signBytesPades — assina em um nível baseline PAdES (0=B-B, 1=B-T, 2=B-LT); tsaUrl é obrigatório para nível ≥ 1 e certs/crls/ocsps carregam o material de revogação B-LT.
  • signBytesPadesOpts — variante com opções em struct de signBytesPades, com comportamento idêntico.

Logging

void setLogLevel(int level)
int getLogLevel()

Define/obtém o nível global de log da biblioteca (0=Off, 1=Error, 2=Warn, 3=Info, 4=Debug, 5=Trace).

Crypto / FIPS

String cryptoActiveProvider()
String cryptoCbom()
String cryptoInventory()
String cryptoPolicy()
int cryptoFipsAvailable()
int cryptoUseFips()
int cryptoSetPolicy(String spec)
  • cryptoActiveProvider — o nome do provedor criptográfico ativo.
  • cryptoCbom — o cryptographic bill of materials (CBOM) em JSON.
  • cryptoInventory — o inventário criptográfico em JSON.
  • cryptoPolicy — a política criptográfica ativa em JSON.
  • cryptoFipsAvailable — se um provedor validado por FIPS está disponível (diferente de zero = sim).
  • cryptoUseFips — alterna para um provedor validado por FIPS; retorna o status.
  • cryptoSetPolicy — define a política criptográfica a partir de uma string de especificação; retorna o status.

Modelos e Configuração Global

String modelManifest()
int prefetchAvailable()
String prefetchModels(String languagesCsv)
int setMaxOpsPerStream(int limit)
int setPreserveUnmappedGlyphs(int preserve)
  • modelManifest — o manifesto dos modelos incluídos em JSON.
  • prefetchAvailable — se o prefetch de modelos está disponível nesta build.
  • prefetchModels — faz prefetch dos modelos de OCR/layout para idiomas separados por vírgula; retorna um relatório JSON.
  • setMaxOpsPerStream — define o limite global de operadores por content stream; retorna o valor anterior.
  • setPreserveUnmappedGlyphs — alterna a preservação de glifos não mapeados; retorna o valor anterior.

Tratamento de Erros

PdfOxideError

Todos os códigos de erro da C ABI que não indicam sucesso são lançados como PdfOxideError.

class PdfOxideError implements Exception {
  final int code;   // C-ABI error code
  final String op;  // the operation that failed
}

Chamar um método em um handle após close() lança um StateError do Dart. EmbeddedFont.fromBytes com dados de fonte inválidos, Certificate.loadFromBytes com um PKCS#12 inválido e PdfDocument.open em um arquivo inexistente, todos lançam 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>)
  }
}

Tipos de Valor

Classes de dados simples retornadas pelos métodos de extração e inspeção.

PdfVersion

Campo Tipo Descrição
major int Versão maior
minor int Versão menor

Bbox

Uma bounding box alinhada aos eixos em pontos do espaço de usuário do PDF.

Campo Tipo Descrição
x, y double Origem no canto inferior esquerdo
width, height double Tamanho da caixa

Char

Campo Tipo Descrição
character int Codepoint Unicode
bbox Bbox Bounding box do glifo
fontName String Nome PostScript da fonte
fontSize double Tamanho da fonte em pontos

Word

Campo Tipo Descrição
text String Texto da palavra
bbox Bbox Bounding box
fontName String Nome da fonte
fontSize double Tamanho da fonte
bold bool Se está em negrito

TextLine

Campo Tipo Descrição
text String Texto da linha
bbox Bbox Bounding box
wordCount int Número de palavras

Table

Membro Tipo Descrição
rowCount int Número de linhas
colCount int Número de colunas
hasHeader bool Se há uma linha de cabeçalho
cell(int row, int col) String Texto de uma célula baseada em 0

Font

Campo Tipo Descrição
name String Nome da fonte
type String Tipo da fonte
encoding String Codificação
embedded bool Se está incorporada
subset bool Se é subset

Image

Campo Tipo Descrição
width, height int Dimensões em pixels
bitsPerComponent int Bits por componente
format String Formato da imagem
colorspace String Espaço de cor
data Uint8List Bytes brutos da imagem

Annotation

Campo Tipo Descrição
type String Tipo da anotação
subtype String Subtipo da anotação
content String Conteúdo de texto
author String Autor
rect Bbox Posição
borderWidth double Largura da borda

Path

Campo Tipo Descrição
bbox Bbox Bounding box
strokeWidth double Largura do traço
hasStroke bool Se é traçado
hasFill bool Se é preenchido
operationCount int Número de operações do caminho

SearchResult

Campo Tipo Descrição
text String Texto correspondente
page int Índice da página baseado em zero
bbox Bbox Bounding box da correspondência

FormField

Campo Tipo Descrição
name String Nome totalmente qualificado do campo
value String Valor atual
type String Tipo do campo (Tx, Btn, Ch, Sig)
readonly bool Se é somente leitura
required bool Se é obrigatório

QuadPoint

Um quad de anotação de destaque (quatro pontos de canto): x1, y1, x2, y2, x3, y3, x4, y4 (double).

AnnotationDetails

Campo Tipo Descrição
type, subtype, content String Tipo/subtipo da anotação e conteúdo
rect Bbox Posição
color int Cor ARGB empacotada
creationDate, modificationDate int Segundos da época Unix (0 se ausente)
hidden, markedDeleted, printable, readOnly bool Flags da anotação
linkUri String URI de destino do link (vazia caso contrário)
iconName String Nome do ícone da anotação de texto (vazio caso contrário)
quadPoints List<QuadPoint> Quad points do destaque (vazia caso contrário)

CertificateValidity

Campo Tipo Descrição
notBefore int Horário de início da validade (segundos da época Unix)
notAfter int Horário de fim da validade (segundos da época Unix)

UaStats

Campo Tipo Descrição
structElements int Elementos de estrutura
images int Imagens
tables int Tabelas
forms int Campos de formulário
annotations int Anotações
pages int Páginas

Element

Campo Tipo Descrição
type String Tipo do elemento (por exemplo, Text, Image, Table)
text String Conteúdo de texto (pode estar vazio)
rect Bbox Bounding box

Exemplo Completo

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

O PDF Oxide oferece bindings nativos para todos os principais ecossistemas: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, R, Julia, Zig, Scala, Clojure, Objective-C e Elixir.

Próximos Passos