Skip to content
PDF Oxide

Referencia de la API de Dart

PDF Oxide ofrece bindings idiomáticos para Dart/Flutter construidos con dart:ffi sobre la C ABI nativa. El paquete carga en tiempo de ejecución la librería precompilada libpdf_oxide.{so,dylib,dll} y expone toda la superficie: extracción, edición, creación, renderizado, formularios, OCR, códigos de barras, firmas digitales y validación de conformidad.

dart pub add pdf_oxide

import 'package:pdf_oxide/pdf_oxide.dart';

Los handles nativos se liberan automáticamente mediante un NativeFinalizer, pero toda clase que posee un handle expone además un close() idempotente que deberías llamar cuando termines (o usar addTearDown/try/finally). Los códigos de error de la C ABI se lanzan como PdfOxideError. Todos los índices de página empiezan en cero.

Para otros lenguajes, consulta la Referencia de la API de Python, la Referencia de la API de Node.js, la Referencia de la API WASM, la Referencia de la API de Rust y Tipos y enums.

PdfDocument

La clase principal para abrir, extraer, renderizar, validar e inspeccionar un PDF.

Constructores / 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 un PDF desde una ruta del sistema de archivos.
  • openFromBytes — abre un PDF desde bytes en memoria.
  • openWithPassword — abre un PDF protegido con contraseña.
  • openFromDocxBytes / openFromPptxBytes / openFromXlsxBytes — abre un documento directamente desde bytes DOCX/PPTX/XLSX.

Información del documento

int get pageCount
PdfVersion get version
bool isEncrypted()
bool hasStructureTree()
bool authenticate(String password)
  • pageCount — número de páginas.
  • version — versión del PDF como PdfVersion(major, minor).
  • isEncrypted — indica si el documento está cifrado.
  • hasStructureTree — indica si es un PDF etiquetado (Tagged PDF) con árbol de estructura.
  • authenticate — autentica un PDF cifrado; devuelve true si tiene éxito y false si la contraseña es incorrecta.

Texto y conversión

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 en bruto de una sola página.
  • toPlainText / toMarkdown / toHtml — convierte una sola página a texto plano, Markdown o HTML.
  • extractStructuredJson — contenido estructurado de la página (spans, disposición) serializado a JSON.
  • toMarkdownAll / toHtmlAll / toPlainTextAll — convierte todo el documento.

Extracción 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 — geometría por glifo, por palabra y por línea.
  • extractTables — tablas detectadas con celdas de lectura diferida (Table.cell).
  • embeddedFonts / embeddedFontsJson / embeddedFontSizes — metadatos de las fuentes incrustadas de una página.
  • embeddedImages — imágenes incrustadas con sus bytes en bruto.
  • pageAnnotations — anotaciones de una página.
  • pageAnnotationDetails — atributos extendidos de anotación (flags, fechas, color, URIs de enlace, nombres de icono, quad points).
  • annotationsToJson — anotaciones serializadas a JSON.
  • extractPaths — elementos de trazado vectorial (gráficos).

Extracción dentro de un rectá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)

Extrae texto, palabras, líneas, tablas o imágenes restringidas a un rectángulo (puntos del espacio de usuario del PDF) de una página.

Extracción y clasificación automáticas

String extractTextAuto(int page)
String extractPageAuto(int page, [String optionsJson = ''])
String extractAllText()
String classifyPage(int page)
String classifyDocument()
  • extractTextAuto — extracción nativa + OCR de imagen según haga falta para una página.
  • extractPageAuto — extracción automática de una sola página con opciones JSON opcionales.
  • extractAllText — el texto de todas las páginas en una sola cadena.
  • classifyPage / classifyDocument — clasificación JSON de la página/documento (escaneado, digital, híbrido, etc.).

Búsqueda

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 en una sola página, en todo el documento, o serializa las coincidencias de una página a JSON.

Renderizado

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 una página a un RenderedImage (format 0=PNG, 1=JPEG).
  • renderPageZoom — renderiza con un factor de zoom.
  • renderPageThumbnail — renderiza una miniatura que cabe dentro de size píxeles.
  • renderPageWithOptions — la superficie completa de RenderOptions (dpi, fondo, anotaciones, calidad JPEG).
  • renderPageWithOptionsEx — añade la supresión de capas OCG con nombre mediante excludedLayers.
  • renderPageRegion — renderiza una región rectangular.
  • renderPageFit — renderiza para encajar dentro de width×height conservando la relación de aspecto.
  • renderPageRaw — renderiza a un búfer RGBA8888 premultiplicado en bruto a dpi.
  • estimateRenderTime — estima el tiempo de renderizado (ms) de una página.

Geometría y elementos de la página

double pageWidth(int pageIndex)
double pageHeight(int pageIndex)
int pageRotation(int pageIndex)
ElementList pageElements(int pageIndex)
Page page(int index)
  • pageWidth / pageHeight — dimensiones de la página en puntos PDF.
  • pageRotation — rotación de la página en grados.
  • pageElements — elementos de disposición de una página como un ElementList.
  • page — una vista Page ligera para extracción encadenada por página.

OCR

bool pageNeedsOcr(int pageIndex)
String ocrExtractText(int pageIndex, [OcrEngine? engine])
  • pageNeedsOcr — indica si una página está escaneada/híbrida y necesita OCR.
  • ocrExtractText — extrae texto mediante OCR; engine puede ser null para usar solo extracción nativa.

Validación y conversión de conformidad

PdfAResults validatePdfA(int level)
UaResults validatePdfUa(int level)
PdfXResults validatePdfX(int level)
bool convertToPdfA(int level)
  • validatePdfA / validatePdfUa / validatePdfX — valida frente a PDF/A, la accesibilidad PDF/UA o PDF/X.
  • convertToPdfA — convierte este documento in situ a PDF/A en el nivel indicado.

Exportación a Office

Uint8List toDocx()
Uint8List toPptx()
Uint8List toXlsx()
Uint8List sourceBytes()
  • toDocx / toPptx / toXlsx — exporta el documento a bytes DOCX/PPTX/XLSX.
  • sourceBytes — los bytes de origen a partir de los cuales se cargó este documento.

Eliminación de encabezados / pies / artefactos

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 — borra el encabezado, el pie o los artefactos marcados de una página; devuelve los elementos borrados.
  • removeHeaders / removeFooters / removeArtifacts — elimina los elementos repetidos de todo el documento usando un umbral de detección.

Formularios

List<FormField> getFormFields()
Uint8List exportFormDataToBytes([int formatType = 0])
void importFormData(String dataPath)
bool importFormFromFile(String filename)
  • getFormFields — campos interactivos de AcroForm.
  • exportFormDataToBytes — exporta los datos del formulario (formatType 0=FDF, 1=XFDF, 2=JSON).
  • importFormData — importa datos de formulario desde la ruta de un archivo FDF/XFDF/JSON.
  • importFormFromFile — importa valores de campo desde un archivo; devuelve si se importó algo.

Estructura y metadatos del documento

String getOutline()
String getPageLabels()
String getXmpMetadata()
bool hasXfa()
String planSplitByBookmarks([String optionsJson = ''])
  • getOutline — el esquema del documento (marcadores) como JSON.
  • getPageLabels — los rangos de etiquetas de página como JSON.
  • getXmpMetadata — metadatos XMP (XML) si los hay.
  • hasXfa — indica si el documento contiene un formulario XFA.
  • planSplitByBookmarks — produce un plan JSON para dividir por marcadores.

Firmas digitales

int sign(Certificate certificate, {String reason = '', String location = ''})
int getSignatureCount()
SignatureInfo getSignature(int index)
int verifyAllSignatures()
bool hasTimestamp()
Dss getDss()
  • sign — firma digitalmente el documento con un Certificate.
  • getSignatureCount — número de firmas presentes.
  • getSignature — el SignatureInfo en un índice.
  • verifyAllSignatures — verifica todas las firmas (estado agregado).
  • hasTimestamp — indica si alguna firma lleva un sello de tiempo.
  • getDss — el almacén de seguridad del documento (Dss).

Ciclo de vida

void close()

Libera el handle nativo ahora (idempotente).

Page

Una vista ligera, basada en cero, de una sola página devuelta por PdfDocument.page(index). Mantiene una referencia fuerte a su documento y delega en los métodos por página del documento.

Miembro Tipo Descripción
index int Índice de página basado en cero 
String text()
String markdown()
String html()
String plainText()

Texto extraído, Markdown, HTML o texto plano de esta página.

Pdf

Un PDF producido (o cargado) para el flujo sencillo de creación/guardado con el builder.

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 — crea un PDF a partir de Markdown, HTML o texto plano.
  • fromImage / fromImageBytes — envuelve un archivo de imagen o sus bytes en un PDF de una sola página.
  • fromHtmlCss — construye a partir de HTML + CSS con una fuente incrustada opcional.
  • fromHtmlCssWithFonts — construye a partir de HTML + CSS con una cascada de fuentes paralela families/fonts.

Métodos

int get pageCount
void save(String path)
Uint8List toBytes()
void close()
  • pageCount — recuento de páginas mediante el punto de entrada pdf_get_page_count.
  • save — guarda en un archivo.
  • toBytes — el contenido del PDF como bytes.
  • close — libera el handle nativo (idempotente).

DocumentEditor

Un PDF abierto para edición in situ: operaciones de página, metadatos, formularios, redacción, aplanado, fusión y guardado cifrado.

Constructores

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

Información y metadatos del documento

int get pageCount
PdfVersion get version
bool isModified()
String getSourcePath()
String getProducer()
void setProducer(String value)
String getCreationDate()
void setCreationDate(String dateStr)
  • isModified — indica si hay modificaciones sin guardar.
  • getSourcePath — la ruta desde la que se abrió el editor.
  • getProducer / setProducer — el campo de metadatos Producer.
  • getCreationDate / setCreationDate — el campo de metadatos CreationDate.

Operaciones 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 — elimina o reordena páginas.
  • rotatePageBy — rotación aditiva; rotateAllPages — rotación relativa de todas las páginas; setPageRotation — absoluta; getPageRotation — actual.
  • cropMargins — recorta los márgenes de todas las páginas.
  • getPageCropBox / setPageCropBox / getPageMediaBox / setPageMediaBox — lee/escribe el CropBox/MediaBox.

Redacción y borrado

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 las redacciones en cola.
  • eraseRegion / eraseRegions / clearEraseRegions — borra uno o varios rectángulos de borrado pendientes, o los limpia.
  • isPageMarkedForRedaction / unmarkPageForRedaction — consulta/limpia la marca de redacción de una página.
  • redactionAdd — encola un rectángulo de redacción con un color de relleno superpuesto.
  • redactionCount — regiones de redacción en cola para una página.
  • redactionApply — aplica de forma destructiva todas las redacciones; devuelve los glifos eliminados.
  • redactionScrubMetadata — elimina metadatos / JavaScript / archivos incrustados; devuelve las construcciones eliminadas.

Aplanado

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 — aplana todos los campos de formulario, o los de una página.
  • flattenAnnotations / flattenAllAnnotations — aplana las anotaciones de una página o de todo el documento.
  • flattenWarningsCount / flattenWarning — advertencias del último guardado con aplanado.
  • isPageMarkedForFlatten / unmarkPageForFlatten — consulta/limpia la marca de aplanado de una página.

Formularios

void setFormFieldValue(String name, String value)
void importFdfBytes(Uint8List data)
void importXfdfBytes(Uint8List data)
  • setFormFieldValue — establece el valor de un campo por su nombre.
  • importFdfBytes / importXfdfBytes — importa valores de AcroForm desde bytes FDF/XFDF.

Fusión / Conversión / Incrustación / Extracción

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 — añade páginas de un PDF en disco o en memoria.
  • convertToPdfA — convierte in situ a PDF/A (nivel 0=A1b … 7=A3u).
  • embedFile — adjunta un archivo con nombre.
  • extractPagesToBytes — extrae un subconjunto de páginas a un nuevo PDF en memoria.

Códigos de barras

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

Estampa un BarcodeImage generado sobre una página en el rectángulo indicado.

Guardado

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 — guarda en un archivo o en un búfer de bytes.
  • saveToBytesWithOptions — guarda con opciones explícitas de compresión / recolección de basura / linealización.
  • saveEncrypted / saveEncryptedToBytes — guardado cifrado con AES-256 a archivo o a bytes.
  • close — libera el handle nativo (idempotente).

DocumentBuilder

Un builder fluido para ensamblar un documento PDF totalmente nuevo.

Crear

static DocumentBuilder create()

Metadatos (fluido)

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 — metadatos del documento.
  • onOpen — JavaScript de apertura del documento.
  • language — idioma del documento.
  • taggedPdfUa1 — habilita el modo etiquetado PDF/UA-1.
  • roleMap — mapea un tipo de estructura personalizado a un tipo PDF estándar.
  • registerEmbeddedFont — registra una fuente bajo un nombre (consume el EmbeddedFont si tiene éxito).

Páginas

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

Abre una página A4, US Letter o de tamaño personalizado como un PageBuilder.

Construir / Guardar

Uint8List build()
void save(String path)
void saveEncrypted(String path, String userPassword, String ownerPassword)
Uint8List toBytesEncrypted(String userPassword, String ownerPassword)
void close()
  • build — construye el PDF y devuelve sus bytes.
  • save — construye y guarda en una ruta.
  • saveEncrypted / toBytesEncrypted — construcción cifrada con AES-256 a archivo o a bytes.
  • close — libera el handle nativo (idempotente).

PageBuilder

Un builder fluido para una sola página, devuelto por DocumentBuilder.page / letterPage / a4Page. Cada operación devuelve this para encadenar. Llama a done() para confirmar la página o a close() para descartarla.

Texto y disposición

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 — establece la fuente/tamaño activos y la posición del cursor.
  • text / heading / paragraph — emite texto, un encabezado de un nivel o un párrafo con ajuste de línea.
  • space / horizontalRule / newline — espaciado vertical, una línea divisoria, un salto de línea.
  • columns — texto a varias columnas con un espacio entre ellas.
  • inline / inlineBold / inlineItalic / inlineColor — tramos de texto en línea.
  • footnote — una marca de referencia más el texto de la nota.
  • textInRect — texto dispuesto dentro de un rectángulo con un código de alineación (0=Izquierda, 1=Centro, 2=Derecha).
  • newPageSameSize — inicia una nueva página del mismo tamaño.

Enlaces

PageBuilder linkUrl(String url)
PageBuilder linkPage(int page)
PageBuilder linkNamed(String destination)
PageBuilder linkJavascript(String script)

Adjunta un enlace a una URL, un enlace interno a una página, un enlace a un destino con nombre o un enlace de JavaScript al último contenido.

Acciones y 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)

Acciones de apertura/cierre de página y scripts de pulsación de tecla/formato/validación/cálculo de campos AcroForm.

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

Anotaciones de marcado sobre el último texto en un color RGB.

Anotaciones / Marca de agua / Sello

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 — una nota adhesiva en el cursor o en una posición explícita.
  • watermark / watermarkConfidential / watermarkDraft — marcas de agua personalizadas o predefinidas.
  • stamp — un sello de goma con nombre.
  • freetext — una anotación de texto libre dentro de un rectángulo.

Imágenes y 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 — coloca una imagen; imageArtifact — coloca una imagen sin contenido (artefacto); imageWithAlt — coloca una imagen con texto alternativo para accesibilidad.
  • barcode1d / barcodeQr — dibuja un código de barras 1-D o un código QR directamente en la página.

Gráficos vectoriales

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

Rectángulos y líneas rellenas y con trazo, incluidos trazos discontinuos con un array de guiones y una fase.

Campos de formulario

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)

Añade widgets de AcroForm: campos de texto, casillas de verificación, cuadros combinados, grupos de botones de opción, botones de acción y campos de firma.

Tablas

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 — almacena en búfer una tabla estática, ordenada por filas.
  • streamingTableBegin / streamingTableBeginV2 — inicia una tabla en streaming (v2 añade modo de ancho de columna, filas de muestra, anchos mínimo/máximo de columna y rowspan).
  • streamingTablePushRow / streamingTablePushRowV2 — añade una fila (v2 con rowspans por celda).
  • streamingTableFlush / streamingTableFinish — vuelca las filas pendientes / cierra la tabla.
  • streamingTableSetBatchSize — filas almacenadas en búfer antes de cada volcado.
  • streamingTableBatchCount / streamingTablePendingRowCount — lotes volcados / filas pendientes.

Ciclo de vida

void done()
void close()
  • done — confirma las operaciones en búfer en el builder padre (consume el handle).
  • close — descarta la página y libera el handle (idempotente).

EmbeddedFont

Una fuente TTF/OTF cargada para incrustar mediante DocumentBuilder.registerEmbeddedFont.

static EmbeddedFont fromFile(String path)
static EmbeddedFont fromBytes(Uint8List data, [String? name])
void close()
  • fromFile — carga una fuente desde la ruta de un archivo.
  • fromBytes — carga desde bytes; name toma por defecto el nombre PostScript de la fuente.
  • close — libera el handle nativo (idempotente).

RenderedImage

Una imagen de página rasterizada devuelta por PdfDocument.renderPage y similares.

int get width
int get height
Uint8List get data
void save(String path)
void close()
  • width / height — dimensiones de la imagen en píxeles.
  • data — bytes de imagen codificados (p. ej. PNG), copiados en Dart.
  • save — escribe la imagen codificada en una ruta.
  • close — libera el handle nativo (idempotente).

ElementList

Los elementos de disposición de una página, producidos por PdfDocument.pageElements.

int get count
Element operator [](int index)
List<Element> toList()
String toJson()
void close()
  • count — número de elementos.
  • operator [] — lee el elemento en un índice.
  • toList — todos los elementos como una lista.
  • toJson — toda la lista serializada a JSON.
  • close — libera el handle nativo (idempotente).

BarcodeImage

Un código de barras 1-D o un código QR generado. Estámpalo en una página con 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 — genera un código QR con un nivel de corrección de errores y un tamaño en píxeles.
  • barcode — genera un código de barras 1-D en un código de formato dado.
  • data / format / confidence — el payload codificado, el código de formato y la confianza de decodificación.
  • imagePng / svg — codifica como bytes PNG o como una cadena SVG.
  • close — libera el handle nativo (idempotente).

OcrEngine

Un motor de OCR respaldado por archivos de modelo de detección/reconocimiento, pasado a PdfDocument.ocrExtractText.

static OcrEngine create(String detModelPath, String recModelPath, String dictPath)
void close()
  • create — crea un motor a partir de las rutas del modelo de detección, el modelo de reconocimiento y el archivo de diccionario.
  • close — libera el handle nativo (idempotente).

Renderer

Un renderizador de página reutilizable configurado con DPI/formato/calidad fijos.

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

Certificate

Credenciales de firma / un certificado X.509, usado por los puntos de entrada de firma.

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 — carga desde un búfer PKCS#12 (.p12/.pfx) con una contraseña.
  • loadFromPem — carga desde cadenas de certificado PEM + clave privada.
  • handle — el handle nativo en bruto (uso avanzado/interoperabilidad).
  • subject / issuer / serial — nombres distinguidos y número de serie.
  • validity — la ventana notBefore/notAfter como un CertificateValidity.
  • isValid — indica si el certificado es válido actualmente.
  • close — libera el handle nativo (idempotente).

Timestamp

Un token de sello de tiempo 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 — analiza un TimeStampToken codificado en DER (o un TSTInfo sin envoltorio).
  • token / messageImprint — el token completo y los bytes del message-imprint hasheado.
  • time — la hora del sello de tiempo (segundos Unix epoch).
  • serial / tsaName / policyOid / hashAlgorithm — el número de serie del token, el nombre de la TSA, el OID de política y el código del algoritmo de hash.
  • verify — verifica criptográficamente el token.
  • close — libera el handle nativo (idempotente).

TsaClient

Un cliente de TSA (autoridad de sellado de tiempo) 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 — crea un cliente para una URL de TSA con autenticación básica y opciones de petición opcionales.
  • requestTimestamp — solicita un sello de tiempo sobre datos en bruto (el cliente los hashea).
  • requestTimestampHash — solicita un sello de tiempo sobre un hash precalculado.
  • close — libera el handle nativo (idempotente).

SignatureInfo

Información sobre una firma digital incrustada en un PDF, obtenida 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 — adopta un handle nativo en bruto (uso avanzado/interoperabilidad).
  • signerName / signingReason / signingLocation / signingTime — metadatos del firmante.
  • certificate — el Certificate del firmante.
  • padesLevel — el código de nivel de línea base PAdES, o -1 si no es PAdES.
  • hasTimestamp / timestamp — indica si existe un sello de tiempo incrustado y el propio Timestamp.
  • addTimestamp — adjunta un sello de tiempo a esta firma.
  • verify — comprobación criptográfica de los atributos del firmante (1 válido / 0 inválido / -1 desconocido).
  • verifyDetached — verifica de extremo a extremo frente a los bytes completos del PDF (1 válido / 0 inválido / -1 desconocido).
  • close — libera el handle nativo (idempotente).

Dss

Un /DSS de documento (document security store), obtenido 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 — adopta un handle DSS en bruto (uso avanzado/interoperabilidad).
  • certCount / crlCount / ocspCount / vriCount — recuentos de certificados, CRLs, respuestas OCSP y entradas VRI.
  • getCert / getCrl / getOcsp — los bytes DER del certificado / CRL / respuesta OCSP en un índice.
  • close — libera el handle nativo (idempotente).

PdfAResults

Resultados de validación PDF/A de PdfDocument.validatePdfA.

bool isCompliant()
List<String> errors()
List<String> warnings()
void close()
  • isCompliant — indica si el documento cumple con PDF/A.
  • errors / warnings — mensajes de error y advertencia de la validación.
  • close — libera el handle nativo (idempotente).

UaResults

Resultados de validación de accesibilidad PDF/UA de PdfDocument.validatePdfUa.

bool isAccessible()
List<String> errors()
List<String> warnings()
UaStats uaStats()
void close()
  • isAccessible — indica si el documento es accesible según PDF/UA.
  • errors / warnings — mensajes de error y advertencia de accesibilidad.
  • uaStats — estadísticas de elementos recopiladas durante la validación.
  • close — libera el handle nativo (idempotente).

PdfXResults

Resultados de validación PDF/X de PdfDocument.validatePdfX.

bool isCompliant()
List<String> errors()
void close()
  • isCompliant — indica si el documento cumple con PDF/X.
  • errors — mensajes de error de la validación.
  • close — libera el handle nativo (idempotente).

Funciones de nivel superior

Estas funciones a nivel de librería viven en el espacio de nombres pdf_oxide.

Fusión y sello de tiempo

Uint8List pdfMerge(List<String> paths)
Uint8List addTimestamp(Uint8List pdf, int sigIndex, String tsaUrl)
  • pdfMerge — fusiona los PDF de las rutas indicadas (en orden) en un solo PDF; devuelve sus bytes.
  • addTimestamp — aplica un sello de tiempo RFC 3161 a una firma, contactando con una TSA; devuelve los bytes del PDF sellado.

Firma

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 — firma bytes PDF en bruto con un certificado; devuelve los bytes firmados.
  • signBytesPades — firma en un nivel de línea base PAdES (0=B-B, 1=B-T, 2=B-LT); tsaUrl es obligatorio para el nivel ≥ 1 y certs/crls/ocsps aportan el material de revocación B-LT.
  • signBytesPadesOpts — variante con opciones de struct de signBytesPades, con comportamiento idéntico.

Registro de logs

void setLogLevel(int level)
int getLogLevel()

Establece/obtiene el nivel global de log de la librería (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 — el nombre del proveedor criptográfico activo.
  • cryptoCbom — la lista de materiales criptográficos (CBOM) como JSON.
  • cryptoInventory — el inventario criptográfico como JSON.
  • cryptoPolicy — la política criptográfica activa como JSON.
  • cryptoFipsAvailable — indica si hay disponible un proveedor validado por FIPS (distinto de cero = sí).
  • cryptoUseFips — cambia a un proveedor validado por FIPS; devuelve el estado.
  • cryptoSetPolicy — establece la política criptográfica a partir de una cadena de especificación; devuelve el estado.

Modelos y configuración global

String modelManifest()
int prefetchAvailable()
String prefetchModels(String languagesCsv)
int setMaxOpsPerStream(int limit)
int setPreserveUnmappedGlyphs(int preserve)
  • modelManifest — el manifiesto de modelos incluidos como JSON.
  • prefetchAvailable — indica si el prefetch de modelos está disponible en esta compilación.
  • prefetchModels — precarga modelos de OCR/disposición para idiomas separados por comas; devuelve un informe JSON.
  • setMaxOpsPerStream — establece el límite global de operadores por flujo de contenido; devuelve el valor anterior.
  • setPreserveUnmappedGlyphs — activa/desactiva la conservación de glifos sin mapear; devuelve el valor anterior.

Manejo de errores

PdfOxideError

Todos los códigos de error de la C ABI distintos de éxito se lanzan como PdfOxideError.

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

Llamar a un método sobre un handle después de close() lanza un StateError de Dart. EmbeddedFont.fromBytes con datos de fuente inválidos, Certificate.loadFromBytes con un PKCS#12 inválido y PdfDocument.open sobre un archivo inexistente lanzan todos 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

Clases de datos planas devueltas por los métodos de extracción e inspección.

PdfVersion

Campo Tipo Descripción
major int Versión mayor
minor int Versión menor

Bbox

Un cuadro delimitador alineado a los ejes en puntos del espacio de usuario del PDF.

Campo Tipo Descripción
x, y double Origen inferior izquierdo
width, height double Tamaño del cuadro

Char

Campo Tipo Descripción
character int Punto de código Unicode
bbox Bbox Cuadro delimitador del glifo
fontName String Nombre PostScript de la fuente
fontSize double Tamaño de fuente en puntos

Word

Campo Tipo Descripción
text String Texto de la palabra
bbox Bbox Cuadro delimitador
fontName String Nombre de la fuente
fontSize double Tamaño de fuente
bold bool Si está en negrita

TextLine

Campo Tipo Descripción
text String Texto de la línea
bbox Bbox Cuadro delimitador
wordCount int Número de palabras

Table

Miembro Tipo Descripción
rowCount int Número de filas
colCount int Número de columnas
hasHeader bool Si hay una fila de encabezado
cell(int row, int col) String Texto de una celda basada en cero

Font

Campo Tipo Descripción
name String Nombre de la fuente
type String Tipo de fuente
encoding String Codificación
embedded bool Si está incrustada
subset bool Si es un subconjunto

Image

Campo Tipo Descripción
width, height int Dimensiones en píxeles
bitsPerComponent int Bits por componente
format String Formato de imagen
colorspace String Espacio de color
data Uint8List Bytes de imagen en bruto

Annotation

Campo Tipo Descripción
type String Tipo de anotación
subtype String Subtipo de anotación
content String Contenido de texto
author String Autor
rect Bbox Posición
borderWidth double Ancho del borde

Path

Campo Tipo Descripción
bbox Bbox Cuadro delimitador
strokeWidth double Ancho del trazo
hasStroke bool Si tiene trazo
hasFill bool Si tiene relleno
operationCount int Número de operaciones de trazado

SearchResult

Campo Tipo Descripción
text String Texto coincidente
page int Índice de página basado en cero
bbox Bbox Cuadro delimitador de la coincidencia

FormField

Campo Tipo Descripción
name String Nombre del campo completamente cualificado
value String Valor actual
type String Tipo de campo (Tx, Btn, Ch, Sig)
readonly bool Si es de solo lectura
required bool Si es obligatorio

QuadPoint

Un quad de anotación de resaltado (cuatro puntos de esquina): x1, y1, x2, y2, x3, y3, x4, y4 (double).

AnnotationDetails

Campo Tipo Descripción
type, subtype, content String Tipo/subtipo de anotación y contenido
rect Bbox Posición
color int Color ARGB empaquetado
creationDate, modificationDate int Segundos Unix epoch (0 si ausente)
hidden, markedDeleted, printable, readOnly bool Flags de anotación
linkUri String URI de destino del enlace (vacío en caso contrario)
iconName String Nombre del icono de la anotación de texto (vacío en caso contrario)
quadPoints List<QuadPoint> Quad points de resaltado (vacío en caso contrario)

CertificateValidity

Campo Tipo Descripción
notBefore int Hora de inicio de validez (segundos Unix epoch)
notAfter int Hora de fin de validez (segundos Unix epoch)

UaStats

Campo Tipo Descripción
structElements int Elementos de estructura
images int Imágenes
tables int Tablas
forms int Campos de formulario
annotations int Anotaciones
pages int Páginas

Element

Campo Tipo Descripción
type String Tipo de elemento (p. ej. Text, Image, Table)
text String Contenido de texto (puede estar vacío)
rect Bbox Cuadro delimitador

Ejemplo 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

PDF Oxide ofrece bindings nativos para todos los ecosistemas principales: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, R, Julia, Zig, Scala, Clojure, Objective-C y Elixir.

Próximos pasos