Skip to content
PDF Oxide

Dart-API-Referenz

PDF Oxide liefert idiomatische Dart/Flutter-Bindings, gebaut mit dart:ffi auf der nativen C-ABI. Das Paket lädt die vorkompilierte libpdf_oxide.{so,dylib,dll} zur Laufzeit und stellt die gesamte Oberfläche bereit — Extraktion, Bearbeitung, Erstellung, Rendering, Formulare, OCR, Barcodes, digitale Signaturen und Konformitätsvalidierung.

dart pub add pdf_oxide

import 'package:pdf_oxide/pdf_oxide.dart';

Native Handles werden automatisch durch einen NativeFinalizer freigegeben, doch jede Handle-besitzende Klasse stellt zusätzlich ein idempotentes close() bereit, das Sie nach Gebrauch aufrufen sollten (oder verwenden Sie addTearDown/try/finally). C-ABI-Fehlercodes werden als PdfOxideError geworfen. Alle Seitenindizes sind 0-basiert.

Für andere Sprachen siehe die Python-API-Referenz, die Node.js-API-Referenz oder die WASM-API-Referenz, die Rust-API-Referenz und Typen & Enums.

PdfDocument

Die zentrale Klasse zum Öffnen, Extrahieren, Rendern, Validieren und Inspizieren eines PDF.

Konstruktoren / 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 — ein PDF aus einem Dateisystempfad öffnen.
  • openFromBytes — ein PDF aus In-Memory-Bytes öffnen.
  • openWithPassword — ein passwortgeschütztes PDF öffnen.
  • openFromDocxBytes / openFromPptxBytes / openFromXlsxBytes — ein Dokument direkt aus DOCX-/PPTX-/XLSX-Bytes öffnen.

Dokumentinformationen

int get pageCount
PdfVersion get version
bool isEncrypted()
bool hasStructureTree()
bool authenticate(String password)
  • pageCount — Anzahl der Seiten.
  • version — PDF-Version als PdfVersion(major, minor).
  • isEncrypted — ob das Dokument verschlüsselt ist.
  • hasStructureTree — ob es sich um ein Tagged PDF mit Strukturbaum handelt.
  • authenticate — ein verschlüsseltes PDF authentifizieren; liefert true bei Erfolg, false bei falschem Passwort.

Text & Konvertierung

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 — reiner extrahierter Text für eine einzelne Seite.
  • toPlainText / toMarkdown / toHtml — eine einzelne Seite in reinen Text, Markdown oder HTML konvertieren.
  • extractStructuredJson — strukturierter Seiteninhalt (Spans, Layout), serialisiert nach JSON.
  • toMarkdownAll / toHtmlAll / toPlainTextAll — das gesamte Dokument konvertieren.

Elementextraktion

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 — Geometrie pro Glyphe, pro Wort und pro Zeile.
  • extractTables — erkannte Tabellen mit verzögert gelesenen Zellen (Table.cell).
  • embeddedFonts / embeddedFontsJson / embeddedFontSizes — Metadaten eingebetteter Schriften für eine Seite.
  • embeddedImages — eingebettete Bilder mit Rohbytes.
  • pageAnnotations — Annotationen auf einer Seite.
  • pageAnnotationDetails — erweiterte Annotationsattribute (Flags, Daten, Farbe, Link-URIs, Icon-Namen, Quad-Punkte).
  • annotationsToJson — Annotationen, serialisiert nach JSON.
  • extractPaths — Vektorpfad-(Grafik-)Elemente.

Extraktion innerhalb eines Rechtecks

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)

Text, Wörter, Zeilen, Tabellen oder Bilder extrahieren, beschränkt auf ein Rechteck (PDF-Benutzerraum-Punkte) auf einer Seite.

Automatische Extraktion & Klassifizierung

String extractTextAuto(int page)
String extractPageAuto(int page, [String optionsJson = ''])
String extractAllText()
String classifyPage(int page)
String classifyDocument()
  • extractTextAuto — native Extraktion plus Bild-OCR nach Bedarf für eine Seite.
  • extractPageAuto — eine einzelne Seite automatisch extrahieren, mit optionalen JSON-Optionen.
  • extractAllText — der Text aller Seiten in einer einzigen Zeichenkette.
  • classifyPage / classifyDocument — JSON-Klassifizierung einer Seite/eines Dokuments (gescannt, digital, hybrid usw.).

Suche

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

Eine einzelne Seite oder das gesamte Dokument durchsuchen oder Seitentreffer nach JSON serialisieren.

Rendering

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 — eine Seite zu einem RenderedImage rendern (format 0=PNG, 1=JPEG).
  • renderPageZoom — mit einem Zoomfaktor rendern.
  • renderPageThumbnail — ein Thumbnail rendern, das in size Pixel passt.
  • renderPageWithOptions — die vollständige RenderOptions-Oberfläche (dpi, Hintergrund, Annotationen, JPEG-Qualität).
  • renderPageWithOptionsEx — ergänzt das Unterdrücken benannter OCG-Ebenen über excludedLayers.
  • renderPageRegion — eine rechteckige Region rendern.
  • renderPageFit — so rendern, dass es unter Beibehaltung des Seitenverhältnisses in width×height passt.
  • renderPageRaw — in einen rohen, vormultiplizierten RGBA8888-Puffer bei dpi rendern.
  • estimateRenderTime — die Renderzeit (ms) für eine Seite schätzen.

Seitengeometrie & Elemente

double pageWidth(int pageIndex)
double pageHeight(int pageIndex)
int pageRotation(int pageIndex)
ElementList pageElements(int pageIndex)
Page page(int index)
  • pageWidth / pageHeight — Seitenabmessungen in PDF-Punkten.
  • pageRotation — Seitendrehung in Grad.
  • pageElements — Layout-Elemente einer Seite als ElementList.
  • page — eine leichtgewichtige Page-Ansicht für verkettete Extraktion pro Seite.

OCR

bool pageNeedsOcr(int pageIndex)
String ocrExtractText(int pageIndex, [OcrEngine? engine])
  • pageNeedsOcr — ob eine Seite gescannt/hybrid ist und OCR benötigt.
  • ocrExtractText — Text per OCR extrahieren; engine darf null sein für rein native Extraktion.

Konformitätsvalidierung & Konvertierung

PdfAResults validatePdfA(int level)
UaResults validatePdfUa(int level)
PdfXResults validatePdfX(int level)
bool convertToPdfA(int level)
  • validatePdfA / validatePdfUa / validatePdfX — gegen PDF/A, PDF/UA-Barrierefreiheit oder PDF/X validieren.
  • convertToPdfA — dieses Dokument an Ort und Stelle auf PDF/A des angegebenen Levels konvertieren.

Office-Export

Uint8List toDocx()
Uint8List toPptx()
Uint8List toXlsx()
Uint8List sourceBytes()
  • toDocx / toPptx / toXlsx — das Dokument in DOCX-/PPTX-/XLSX-Bytes exportieren.
  • sourceBytes — die ursprünglichen Quellbytes, aus denen dieses Dokument geladen wurde.

Entfernen von Kopfzeile / Fußzeile / Artefakten

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 — die Kopfzeile, Fußzeile oder markierte Artefakte auf einer Seite löschen; liefert die Anzahl gelöschter Elemente.
  • removeHeaders / removeFooters / removeArtifacts — wiederkehrende Seitenelemente dokumentweit anhand eines Erkennungsschwellwerts entfernen.

Formulare

List<FormField> getFormFields()
Uint8List exportFormDataToBytes([int formatType = 0])
void importFormData(String dataPath)
bool importFormFromFile(String filename)
  • getFormFields — interaktive AcroForm-Felder.
  • exportFormDataToBytes — Formulardaten exportieren (formatType 0=FDF, 1=XFDF, 2=JSON).
  • importFormData — Formulardaten aus einem FDF-/XFDF-/JSON-Dateipfad importieren.
  • importFormFromFile — Feldwerte aus einer Datei importieren; liefert, ob etwas importiert wurde.

Dokumentstruktur & Metadaten

String getOutline()
String getPageLabels()
String getXmpMetadata()
bool hasXfa()
String planSplitByBookmarks([String optionsJson = ''])
  • getOutline — die Dokumentgliederung (Lesezeichen) als JSON.
  • getPageLabels — Seitenbeschriftungsbereiche als JSON.
  • getXmpMetadata — XMP-Metadaten (XML), falls vorhanden.
  • hasXfa — ob das Dokument ein XFA-Formular enthält.
  • planSplitByBookmarks — einen JSON-Plan zum Aufteilen nach Lesezeichen erzeugen.

Digitale Signaturen

int sign(Certificate certificate, {String reason = '', String location = ''})
int getSignatureCount()
SignatureInfo getSignature(int index)
int verifyAllSignatures()
bool hasTimestamp()
Dss getDss()
  • sign — das Dokument mit einem Certificate digital signieren.
  • getSignatureCount — Anzahl der vorhandenen Signaturen.
  • getSignature — die SignatureInfo an einem Index.
  • verifyAllSignatures — alle Signaturen verifizieren (Gesamtstatus).
  • hasTimestamp — ob irgendeine Signatur einen Zeitstempel trägt.
  • getDss — der Document Security Store (Dss).

Lebenszyklus

void close()

Den nativen Handle jetzt freigeben (idempotent).

Page

Eine leichtgewichtige, 0-basierte Ansicht einer einzelnen Seite, zurückgegeben von PdfDocument.page(index). Hält eine starke Referenz auf sein Dokument und delegiert an dessen Methoden pro Seite.

Member Typ Beschreibung
index int 0-basierter Seitenindex 
String text()
String markdown()
String html()
String plainText()

Extrahierter Text, Markdown, HTML oder reiner Text für diese Seite.

Pdf

Ein PDF, das für den einfachen Builder-/Speicherablauf erzeugt (oder geladen) wurde.

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 — ein PDF aus Markdown, HTML oder reinem Text erstellen.
  • fromImage / fromImageBytes — eine Bilddatei oder Bildbytes in ein einseitiges PDF einbetten.
  • fromHtmlCss — aus HTML + CSS mit einer optionalen eingebetteten Schrift bauen.
  • fromHtmlCssWithFonts — aus HTML + CSS mit einer parallelen families/fonts-Schriftkaskade bauen.

Methoden

int get pageCount
void save(String path)
Uint8List toBytes()
void close()
  • pageCount — Seitenanzahl über den Einstiegspunkt pdf_get_page_count.
  • save — in eine Datei speichern.
  • toBytes — der PDF-Inhalt als Bytes.
  • close — den nativen Handle freigeben (idempotent).

DocumentEditor

Ein geöffnetes PDF zur In-Place-Bearbeitung: Seitenoperationen, Metadaten, Formulare, Redaktion, Flatten, Zusammenführen und verschlüsseltes Speichern.

Konstruktoren

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

Dokumentinformationen & Metadaten

int get pageCount
PdfVersion get version
bool isModified()
String getSourcePath()
String getProducer()
void setProducer(String value)
String getCreationDate()
void setCreationDate(String dateStr)
  • isModified — ob es ungespeicherte Änderungen gibt.
  • getSourcePath — der Pfad, aus dem der Editor geöffnet wurde.
  • getProducer / setProducer — das Producer-Metadatenfeld.
  • getCreationDate / setCreationDate — das CreationDate-Metadatenfeld.

Seitenoperationen

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 — Seiten löschen oder umordnen.
  • rotatePageBy — additive Drehung; rotateAllPages — relative Drehung aller Seiten; setPageRotation — absolut; getPageRotation — aktuell.
  • cropMargins — Ränder auf jeder Seite beschneiden.
  • getPageCropBox / setPageCropBox / getPageMediaBox / setPageMediaBox — die CropBox/MediaBox lesen/schreiben.

Redaktion & Löschen

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 — eingereihte Redaktionen anwenden.
  • eraseRegion / eraseRegions / clearEraseRegions — ein oder mehrere Löschrechtecke löschen oder ausstehende leeren.
  • isPageMarkedForRedaction / unmarkPageForRedaction — die Redaktionsmarkierung einer Seite abfragen/aufheben.
  • redactionAdd — ein Redaktionsrechteck mit einer Overlay-Füllfarbe einreihen.
  • redactionCount — eingereihte Redaktionsregionen für eine Seite.
  • redactionApply — alle Redaktionen destruktiv anwenden; liefert die Anzahl entfernter Glyphen.
  • redactionScrubMetadata — Metadaten / JavaScript / eingebettete Dateien entfernen; liefert die Anzahl entfernter Konstrukte.

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 — alle Formularfelder abflachen oder nur die auf einer Seite.
  • flattenAnnotations / flattenAllAnnotations — Annotationen auf einer Seite oder dokumentweit abflachen.
  • flattenWarningsCount / flattenWarning — Warnungen vom letzten Flatten-Speichervorgang.
  • isPageMarkedForFlatten / unmarkPageForFlatten — die Flatten-Markierung einer Seite abfragen/aufheben.

Formulare

void setFormFieldValue(String name, String value)
void importFdfBytes(Uint8List data)
void importXfdfBytes(Uint8List data)
  • setFormFieldValue — einen Feldwert anhand des Namens setzen.
  • importFdfBytes / importXfdfBytes — AcroForm-Werte aus FDF-/XFDF-Bytes importieren.

Zusammenführen / Konvertieren / Einbetten / Extrahieren

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 — Seiten aus einem PDF auf der Festplatte oder im Speicher anhängen.
  • convertToPdfA — an Ort und Stelle auf PDF/A konvertieren (Level 0=A1b … 7=A3u).
  • embedFile — eine benannte Datei anhängen.
  • extractPagesToBytes — eine Teilmenge von Seiten in ein neues In-Memory-PDF extrahieren.

Barcodes

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

Ein generiertes BarcodeImage an dem angegebenen Rechteck auf eine Seite stempeln.

Speichern

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 — in eine Datei oder einen Byte-Puffer speichern.
  • saveToBytesWithOptions — mit expliziten Optionen für Komprimierung / Garbage-Collect / Linearisierung speichern.
  • saveEncrypted / saveEncryptedToBytes — AES-256-verschlüsseltes Speichern in Datei oder Bytes.
  • close — den nativen Handle freigeben (idempotent).

DocumentBuilder

Ein fluider Builder zum Zusammensetzen eines brandneuen PDF-Dokuments.

Erstellen

static DocumentBuilder create()

Metadaten (fluide)

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 — Dokumentmetadaten.
  • onOpen — JavaScript beim Öffnen des Dokuments.
  • language — Dokumentsprache.
  • taggedPdfUa1 — den getaggten PDF/UA-1-Modus aktivieren.
  • roleMap — einen benutzerdefinierten Strukturtyp auf einen Standard-PDF-Typ abbilden.
  • registerEmbeddedFont — eine Schrift unter einem Namen registrieren (verbraucht bei Erfolg die EmbeddedFont).

Seiten

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

Eine A4-, US-Letter- oder benutzerdefiniert dimensionierte Seite als PageBuilder öffnen.

Bauen / Speichern

Uint8List build()
void save(String path)
void saveEncrypted(String path, String userPassword, String ownerPassword)
Uint8List toBytesEncrypted(String userPassword, String ownerPassword)
void close()
  • build — das PDF bauen und seine Bytes zurückgeben.
  • save — bauen und in einen Pfad speichern.
  • saveEncrypted / toBytesEncrypted — AES-256-verschlüsseltes Bauen in Datei oder Bytes.
  • close — den nativen Handle freigeben (idempotent).

PageBuilder

Ein fluider Builder für eine einzelne Seite, zurückgegeben von DocumentBuilder.page / letterPage / a4Page. Jede Operation liefert this für das Verketten. Rufen Sie done() auf, um die Seite festzuschreiben, oder close(), um sie zu verwerfen.

Text & 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 — die aktive Schrift/Größe und die Cursorposition setzen.
  • text / heading / paragraph — Text, eine Überschrift auf einer Ebene oder einen umbrochenen Absatz ausgeben.
  • space / horizontalRule / newline — vertikaler Abstand, eine Linie, ein Zeilenumbruch.
  • columns — mehrspaltiger Text mit einem Abstand.
  • inline / inlineBold / inlineItalic / inlineColor — Inline-Textläufe.
  • footnote — eine Referenzmarkierung plus Notiztext.
  • textInRect — Text, der innerhalb eines Rechtecks mit einem Ausrichtungscode angeordnet wird (0=Links, 1=Zentriert, 2=Rechts).
  • newPageSameSize — eine neue Seite derselben Größe beginnen.
PageBuilder linkUrl(String url)
PageBuilder linkPage(int page)
PageBuilder linkNamed(String destination)
PageBuilder linkJavascript(String script)

Einen URL-Link, internen Seitenlink, Link zu einem benannten Ziel oder JavaScript-Link an den letzten Inhalt anhängen.

Aktionen & Feld-Skripte

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

Aktionen beim Öffnen/Schließen der Seite sowie AcroForm-Feld-Skripte für Tastendruck/Format/Validierung/Berechnung.

Text-Markup

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)

Markup-Annotationen über dem letzten Text in einer RGB-Farbe.

Annotationen / Wasserzeichen / Stempel

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 — eine Haftnotiz an der Cursorposition oder einer expliziten Position.
  • watermark / watermarkConfidential / watermarkDraft — benutzerdefinierte oder voreingestellte Wasserzeichen.
  • stamp — ein benannter Stempel.
  • freetext — eine Freitext-Annotation in einem Rechteck.

Bilder & Barcodes

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 — ein Bild platzieren; imageArtifact — ein Nicht-Inhalts-(Artefakt-)Bild platzieren; imageWithAlt — ein Bild mit Alternativtext zur Barrierefreiheit platzieren.
  • barcode1d / barcodeQr — einen 1-D-Barcode oder QR-Code direkt auf die Seite zeichnen.

Vektorgrafik

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

Gefüllte und umrandete Rechtecke und Linien, einschließlich gestrichelter Striche mit Strichmuster (dash array) und Phase.

Formularfelder

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-Widgets hinzufügen: Textfelder, Kontrollkästchen, Kombinationsfelder, Optionsfeldgruppen, Schaltflächen und Signaturfelder.

Tabellen

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 — eine statische, zeilenweise Tabelle puffern.
  • streamingTableBegin / streamingTableBeginV2 — eine Streaming-Tabelle beginnen (v2 ergänzt Spaltenbreiten-Modus, Beispielzeilen, minimale/maximale Spaltenbreiten und Rowspan).
  • streamingTablePushRow / streamingTablePushRowV2 — eine Zeile einreihen (v2 mit Rowspans pro Zelle).
  • streamingTableFlush / streamingTableFinish — ausstehende Zeilen leeren / die Tabelle schließen.
  • streamingTableSetBatchSize — Zeilen, die vor jedem Flush gepuffert werden.
  • streamingTableBatchCount / streamingTablePendingRowCount — geleerte Batches / ausstehende Zeilen.

Lebenszyklus

void done()
void close()
  • done — die gepufferten Operationen an den übergeordneten Builder festschreiben (verbraucht den Handle).
  • close — die Seite verwerfen und den Handle freigeben (idempotent).

EmbeddedFont

Eine geladene TTF-/OTF-Schrift zum Einbetten über DocumentBuilder.registerEmbeddedFont.

static EmbeddedFont fromFile(String path)
static EmbeddedFont fromBytes(Uint8List data, [String? name])
void close()
  • fromFile — eine Schrift aus einem Dateipfad laden.
  • fromBytes — aus Bytes laden; name ist standardmäßig der PostScript-Name der Schrift.
  • close — den nativen Handle freigeben (idempotent).

RenderedImage

Ein gerastertes Seitenbild, zurückgegeben von PdfDocument.renderPage und Verwandten.

int get width
int get height
Uint8List get data
void save(String path)
void close()
  • width / height — Bildabmessungen in Pixeln.
  • data — kodierte Bildbytes (z. B. PNG), nach Dart kopiert.
  • save — das kodierte Bild in einen Pfad schreiben.
  • close — den nativen Handle freigeben (idempotent).

ElementList

Die Layout-Elemente einer Seite, erzeugt von PdfDocument.pageElements.

int get count
Element operator [](int index)
List<Element> toList()
String toJson()
void close()
  • count — Anzahl der Elemente.
  • operator [] — das Element an einem Index lesen.
  • toList — alle Elemente als Liste.
  • toJson — die gesamte Liste, serialisiert nach JSON.
  • close — den nativen Handle freigeben (idempotent).

BarcodeImage

Ein generierter 1-D-Barcode oder QR-Code. Mit DocumentEditor.addBarcodeToPage auf eine Seite stempeln.

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 — einen QR-Code mit einem Fehlerkorrektur-Level und einer Pixelgröße generieren.
  • barcode — einen 1-D-Barcode in einem gegebenen Formatcode generieren.
  • data / format / confidence — die kodierte Nutzlast, der Formatcode und die Dekodierungs-Konfidenz.
  • imagePng / svg — als PNG-Bytes oder SVG-Zeichenkette kodieren.
  • close — den nativen Handle freigeben (idempotent).

OcrEngine

Eine OCR-Engine, gestützt auf Modelldateien für Erkennung/Recognition, übergeben an PdfDocument.ocrExtractText.

static OcrEngine create(String detModelPath, String recModelPath, String dictPath)
void close()
  • create — eine Engine aus den Pfaden zu Erkennungsmodell, Recognition-Modell und Wörterbuchdatei erstellen.
  • close — den nativen Handle freigeben (idempotent).

Renderer

Ein wiederverwendbarer Seiten-Renderer, konfiguriert mit festem DPI/Format/Qualität.

static Renderer create({int dpi = 150, int format = 0, int quality = 90, bool antiAlias = true})
void close()
  • create — einen Renderer erstellen (format 0=PNG, 1=JPEG; quality 1…100).
  • close — den nativen Handle freigeben (idempotent).

Certificate

Signierungsdaten / ein X.509-Zertifikat, verwendet von den Signierungs-Einstiegspunkten.

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 — aus einem PKCS#12-(.p12/.pfx-)Puffer mit einem Passwort laden.
  • loadFromPem — aus PEM-Zertifikat- + Private-Key-Zeichenketten laden.
  • handle — der rohe native Handle (fortgeschrittene/Interop-Nutzung).
  • subject / issuer / serial — Distinguished Names und Seriennummer.
  • validity — das notBefore/notAfter-Fenster als CertificateValidity.
  • isValid — ob das Zertifikat derzeit gültig ist.
  • close — den nativen Handle freigeben (idempotent).

Timestamp

Ein RFC-3161-Zeitstempel-Token.

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 — ein DER-kodiertes TimeStampToken (oder ein bloßes TSTInfo) parsen.
  • token / messageImprint — das vollständige Token und die gehashten Message-Imprint-Bytes.
  • time — Zeitstempelzeit (Unix-Epoch-Sekunden).
  • serial / tsaName / policyOid / hashAlgorithm — Token-Seriennummer, TSA-Name, Policy-OID und Hash-Algorithmus-Code.
  • verify — das Token kryptografisch verifizieren.
  • close — den nativen Handle freigeben (idempotent).

TsaClient

Ein RFC-3161-TSA-(Timestamp-Authority-)Client.

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 — einen Client für eine TSA-URL mit optionaler Basic-Auth und Anfrageoptionen erstellen.
  • requestTimestamp — einen Zeitstempel über Rohdaten anfordern (der Client hasht sie).
  • requestTimestampHash — einen Zeitstempel über einen vorab berechneten Hash anfordern.
  • close — den nativen Handle freigeben (idempotent).

SignatureInfo

Informationen über eine in ein PDF eingebettete digitale Signatur, von 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 — einen rohen nativen Handle übernehmen (fortgeschrittene/Interop-Nutzung).
  • signerName / signingReason / signingLocation / signingTime — Metadaten des Unterzeichners.
  • certificate — das Certificate des Unterzeichners.
  • padesLevel — PAdES-Baseline-Level-Code oder -1, falls kein PAdES.
  • hasTimestamp / timestamp — ob ein eingebetteter Zeitstempel existiert, und der Timestamp selbst.
  • addTimestamp — dieser Signatur einen Zeitstempel anhängen.
  • verify — Kryptografieprüfung der Signierattribute (1 gültig / 0 ungültig / -1 unbekannt).
  • verifyDetached — durchgängig gegen die vollständigen PDF-Bytes verifizieren (1 gültig / 0 ungültig / -1 unbekannt).
  • close — den nativen Handle freigeben (idempotent).

Dss

Ein Dokument-/DSS (Document Security Store), von 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 — einen rohen DSS-Handle übernehmen (fortgeschrittene/Interop-Nutzung).
  • certCount / crlCount / ocspCount / vriCount — Anzahl der Zertifikate, CRLs, OCSP-Antworten und VRI-Einträge.
  • getCert / getCrl / getOcsp — die DER-Bytes des Zertifikats / der CRL / der OCSP-Antwort an einem Index.
  • close — den nativen Handle freigeben (idempotent).

PdfAResults

PDF/A-Validierungsergebnisse von PdfDocument.validatePdfA.

bool isCompliant()
List<String> errors()
List<String> warnings()
void close()
  • isCompliant — ob das Dokument PDF/A-konform ist.
  • errors / warnings — Validierungsfehler- und Warnmeldungen.
  • close — den nativen Handle freigeben (idempotent).

UaResults

PDF/UA-Barrierefreiheits-Validierungsergebnisse von PdfDocument.validatePdfUa.

bool isAccessible()
List<String> errors()
List<String> warnings()
UaStats uaStats()
void close()
  • isAccessible — ob das Dokument PDF/UA-barrierefrei ist.
  • errors / warnings — Barrierefreiheits-Fehler- und Warnmeldungen.
  • uaStats — während der Validierung gesammelte Element-Statistiken.
  • close — den nativen Handle freigeben (idempotent).

PdfXResults

PDF/X-Validierungsergebnisse von PdfDocument.validatePdfX.

bool isCompliant()
List<String> errors()
void close()
  • isCompliant — ob das Dokument PDF/X-konform ist.
  • errors — Validierungsfehlermeldungen.
  • close — den nativen Handle freigeben (idempotent).

Funktionen auf oberster Ebene

Diese Funktionen auf Bibliotheksebene liegen im Namensraum pdf_oxide.

Zusammenführen & Zeitstempel

Uint8List pdfMerge(List<String> paths)
Uint8List addTimestamp(Uint8List pdf, int sigIndex, String tsaUrl)
  • pdfMerge — die PDFs an den angegebenen Pfaden (in Reihenfolge) zu einem PDF zusammenführen; liefert dessen Bytes.
  • addTimestamp — einen RFC-3161-Zeitstempel auf eine Signatur anwenden und dabei eine TSA kontaktieren; liefert die mit Zeitstempel versehenen PDF-Bytes.

Signieren

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 — rohe PDF-Bytes mit einem Zertifikat signieren; liefert die signierten Bytes.
  • signBytesPades — auf einem PAdES-Baseline-Level signieren (0=B-B, 1=B-T, 2=B-LT); tsaUrl ist für Level ≥ 1 erforderlich, und certs/crls/ocsps tragen das B-LT-Sperrmaterial.
  • signBytesPadesOpts — Struct-Optionen-Variante von signBytesPades mit identischem Verhalten.

Logging

void setLogLevel(int level)
int getLogLevel()

Den globalen Log-Level der Bibliothek setzen/abfragen (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 — der Name des aktiven kryptografischen Providers.
  • cryptoCbom — die kryptografische Stückliste (CBOM) als JSON.
  • cryptoInventory — das kryptografische Inventar als JSON.
  • cryptoPolicy — die aktive kryptografische Policy als JSON.
  • cryptoFipsAvailable — ob ein FIPS-validierter Provider verfügbar ist (ungleich null = ja).
  • cryptoUseFips — zu einem FIPS-validierten Provider wechseln; liefert den Status.
  • cryptoSetPolicy — die kryptografische Policy aus einer Spec-Zeichenkette setzen; liefert den Status.

Modelle & globale Konfiguration

String modelManifest()
int prefetchAvailable()
String prefetchModels(String languagesCsv)
int setMaxOpsPerStream(int limit)
int setPreserveUnmappedGlyphs(int preserve)
  • modelManifest — das gebündelte Modell-Manifest als JSON.
  • prefetchAvailable — ob Modell-Prefetch in diesem Build verfügbar ist.
  • prefetchModels — OCR-/Layout-Modelle für kommagetrennte Sprachen vorab laden; liefert einen JSON-Bericht.
  • setMaxOpsPerStream — das globale Operatorlimit pro Content-Stream setzen; liefert den vorherigen Wert.
  • setPreserveUnmappedGlyphs — die Beibehaltung nicht zugeordneter Glyphen umschalten; liefert den vorherigen Wert.

Fehlerbehandlung

PdfOxideError

Alle nicht erfolgreichen C-ABI-Fehlercodes werden als PdfOxideError geworfen.

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

Der Aufruf einer Methode auf einem Handle nach close() wirft einen Dart-StateError. EmbeddedFont.fromBytes mit ungültigen Schriftdaten, Certificate.loadFromBytes mit einem ungültigen PKCS#12 und PdfDocument.open auf einer fehlenden Datei lösen allesamt PdfOxideError aus.

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

Werttypen

Reine Datenklassen, die von Extraktions- und Inspektionsmethoden zurückgegeben werden.

PdfVersion

Feld Typ Beschreibung
major int Hauptversion
minor int Nebenversion

Bbox

Ein achsenparalleler Begrenzungsrahmen in PDF-Benutzerraum-Punkten.

Feld Typ Beschreibung
x, y double Ursprung unten links
width, height double Größe des Rahmens

Char

Feld Typ Beschreibung
character int Unicode-Codepoint
bbox Bbox Glyphen-Begrenzungsrahmen
fontName String PostScript-Schriftname
fontSize double Schriftgröße in Punkten

Word

Feld Typ Beschreibung
text String Wort-Text
bbox Bbox Begrenzungsrahmen
fontName String Schriftname
fontSize double Schriftgröße
bold bool Ob fett

TextLine

Feld Typ Beschreibung
text String Zeilentext
bbox Bbox Begrenzungsrahmen
wordCount int Anzahl der Wörter

Table

Member Typ Beschreibung
rowCount int Anzahl der Zeilen
colCount int Anzahl der Spalten
hasHeader bool Ob eine Kopfzeile vorhanden ist
cell(int row, int col) String Text einer 0-basierten Zelle

Font

Feld Typ Beschreibung
name String Schriftname
type String Schriftart-Typ
encoding String Kodierung
embedded bool Ob eingebettet
subset bool Ob Subset

Image

Feld Typ Beschreibung
width, height int Pixelabmessungen
bitsPerComponent int Bits pro Komponente
format String Bildformat
colorspace String Farbraum
data Uint8List Rohe Bildbytes

Annotation

Feld Typ Beschreibung
type String Annotationstyp
subtype String Annotations-Untertyp
content String Textinhalt
author String Autor
rect Bbox Position
borderWidth double Rahmenbreite

Path

Feld Typ Beschreibung
bbox Bbox Begrenzungsrahmen
strokeWidth double Strichbreite
hasStroke bool Ob umrandet
hasFill bool Ob gefüllt
operationCount int Anzahl der Pfadoperationen

SearchResult

Feld Typ Beschreibung
text String Gefundener Text
page int 0-basierter Seitenindex
bbox Bbox Begrenzungsrahmen des Treffers

FormField

Feld Typ Beschreibung
name String Vollständig qualifizierter Feldname
value String Aktueller Wert
type String Feldtyp (Tx, Btn, Ch, Sig)
readonly bool Ob schreibgeschützt
required bool Ob erforderlich

QuadPoint

Ein Quad einer Highlight-Annotation (vier Eckpunkte): x1, y1, x2, y2, x3, y3, x4, y4 (double).

AnnotationDetails

Feld Typ Beschreibung
type, subtype, content String Annotationstyp/-untertyp und -inhalt
rect Bbox Position
color int Gepackte ARGB-Farbe
creationDate, modificationDate int Unix-Epoch-Sekunden (0, falls nicht vorhanden)
hidden, markedDeleted, printable, readOnly bool Annotations-Flags
linkUri String Link-Ziel-URI (sonst leer)
iconName String Icon-Name der Text-Annotation (sonst leer)
quadPoints List<QuadPoint> Highlight-Quad-Punkte (sonst leer)

CertificateValidity

Feld Typ Beschreibung
notBefore int Gültig-ab-Zeit (Unix-Epoch-Sekunden)
notAfter int Gültig-bis-Zeit (Unix-Epoch-Sekunden)

UaStats

Feld Typ Beschreibung
structElements int Strukturelemente
images int Bilder
tables int Tabellen
forms int Formularfelder
annotations int Annotationen
pages int Seiten

Element

Feld Typ Beschreibung
type String Elementtyp (z. B. Text, Image, Table)
text String Textinhalt (kann leer sein)
rect Bbox Begrenzungsrahmen

Vollständiges Beispiel

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 bietet native Bindings für jedes wichtige Ökosystem: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, R, Julia, Zig, Scala, Clojure, Objective-C und Elixir.

Nächste Schritte