PdfDocument class

A loaded PDF document.

PdfDocument is the top-level Dart abstraction for a PDF file. It mirrors the PDFium model: FPDF_LoadMemDocument64 returns a single document handle used for all subsequent operations. PdfDocument is the Dart owner of that handle and exposes document-level capabilities as async methods.

Loading

Use fromBytes to load a document from raw PDF bytes:

final bytes = await File('document.pdf').readAsBytes();
final doc = await PdfDocument.fromBytes(bytes);

Error handling

fromBytes throws PdfExtractionException when the document cannot be loaded. Inspect PdfExtractionException.error to distinguish between PdfError.passwordRequired and PdfError.invalidDocument so callers can give users an actionable message.

Resource management

Always call close when the document is no longer needed to release the native PDFium handle:

final doc = await PdfDocument.fromBytes(bytes);
try {
  final meta = await doc.getMetadata();
  // use meta…
} finally {
  await doc.close();
}

A Finalizer is registered internally as a safety net in case close is forgotten, but explicit disposal is strongly preferred.

Platform support

The public API is identical on all platforms. The backend differs:

On native platforms all PDFium calls run on a dedicated Isolate so the caller's isolate (typically the UI isolate) is never blocked. On web, dart:isolate is not supported on any compile target, so PDFium calls run inside a dedicated Web Worker instead, communicating with the main thread via a hand-rolled postMessage protocol.

Future capabilities

PdfDocument is designed to be the foundation for future capabilities: text extraction (document.openTextExtractor()), annotation access, and page rendering. This plan establishes the class and its metadata surface; future plans add capabilities without breaking the existing API.