Skip to content
PDF Oxide

Справочник API Dart

PDF Oxide поставляет идиоматичные привязки для Dart/Flutter, построенные на dart:ffi поверх нативного C ABI. Пакет загружает заранее собранную библиотеку libpdf_oxide.{so,dylib,dll} во время выполнения и предоставляет полную функциональность — извлечение, редактирование, создание, рендеринг, формы, OCR, штрихкоды, цифровые подписи и проверку соответствия.

dart pub add pdf_oxide

import 'package:pdf_oxide/pdf_oxide.dart';

Нативные дескрипторы освобождаются автоматически с помощью NativeFinalizer, но каждый класс, владеющий дескриптором, также предоставляет идемпотентный метод close(), который следует вызывать по завершении работы (либо используйте addTearDown/try/finally). Коды ошибок C ABI выбрасываются как PdfOxideError. Все индексы страниц отсчитываются от нуля.

Для других языков см. Справочник API Python, Справочник API Node.js или Справочник API WASM, Справочник API Rust и Типы и перечисления.

PdfDocument

Основной класс для открытия, извлечения, рендеринга, валидации и инспекции PDF.

Конструкторы / фабрики

static PdfDocument open(String path)
static PdfDocument openFromBytes(Uint8List data)
static PdfDocument openWithPassword(String path, String password)
static PdfDocument openFromDocxBytes(Uint8List data)
static PdfDocument openFromPptxBytes(Uint8List data)
static PdfDocument openFromXlsxBytes(Uint8List data)
  • open — открыть PDF по пути в файловой системе.
  • openFromBytes — открыть PDF из байтов в памяти.
  • openWithPassword — открыть PDF, защищённый паролем.
  • openFromDocxBytes / openFromPptxBytes / openFromXlsxBytes — открыть документ напрямую из байтов DOCX/PPTX/XLSX.

Сведения о документе

int get pageCount
PdfVersion get version
bool isEncrypted()
bool hasStructureTree()
bool authenticate(String password)
  • pageCount — количество страниц.
  • version — версия PDF в виде PdfVersion(major, minor).
  • isEncrypted — зашифрован ли документ.
  • hasStructureTree — является ли это размеченным (Tagged) PDF с деревом структуры.
  • authenticate — аутентификация зашифрованного PDF; возвращает true при успехе и false при неверном пароле.

Текст и конвертация

String extractText(int page)
String toPlainText(int page)
String toMarkdown(int page)
String toHtml(int page)
String extractStructuredJson(int page)
String toMarkdownAll()
String toHtmlAll()
String toPlainTextAll()
  • extractText — обычный извлечённый текст одной страницы.
  • toPlainText / toMarkdown / toHtml — преобразование одной страницы в обычный текст, Markdown или HTML.
  • extractStructuredJson — структурированное содержимое страницы (фрагменты, разметка), сериализованное в JSON.
  • toMarkdownAll / toHtmlAll / toPlainTextAll — преобразование всего документа.

Извлечение элементов

List<Char> extractChars(int page)
List<Word> extractWords(int page)
List<TextLine> extractTextLines(int page)
List<Table> extractTables(int page)
List<Font> embeddedFonts(int page)
String embeddedFontsJson(int page)
List<double> embeddedFontSizes(int page)
List<Image> embeddedImages(int page)
List<Annotation> pageAnnotations(int page)
List<AnnotationDetails> pageAnnotationDetails(int page)
String annotationsToJson(int page)
List<Path> extractPaths(int page)
  • extractChars / extractWords / extractTextLines — геометрия по глифам, словам и строкам.
  • extractTables — обнаруженные таблицы с лениво считываемыми ячейками (Table.cell).
  • embeddedFonts / embeddedFontsJson / embeddedFontSizes — метаданные встроенных шрифтов страницы.
  • embeddedImages — встроенные изображения с исходными байтами.
  • pageAnnotations — аннотации на странице.
  • pageAnnotationDetails — расширенные атрибуты аннотаций (флаги, даты, цвет, URI ссылок, имена иконок, точки квадрантов).
  • annotationsToJson — аннотации, сериализованные в JSON.
  • extractPaths — векторные графические элементы (пути).

Извлечение в пределах прямоугольника

String extractTextInRect(int page, double x, double y, double w, double h)
List<Word> extractWordsInRect(int page, double x, double y, double w, double h)
List<TextLine> extractLinesInRect(int page, double x, double y, double w, double h)
List<Table> extractTablesInRect(int page, double x, double y, double w, double h)
List<Image> extractImagesInRect(int page, double x, double y, double w, double h)

Извлечение текста, слов, строк, таблиц или изображений, ограниченное прямоугольником (в точках пользовательского пространства PDF) на странице.

Автоматическое извлечение и классификация

String extractTextAuto(int page)
String extractPageAuto(int page, [String optionsJson = ''])
String extractAllText()
String classifyPage(int page)
String classifyDocument()
  • extractTextAuto — нативное извлечение плюс OCR изображений по мере необходимости для страницы.
  • extractPageAuto — автоматическое извлечение одной страницы с необязательными параметрами в формате JSON.
  • extractAllText — текст всех страниц в одной строке.
  • classifyPage / classifyDocument — классификация страницы/документа в JSON (отсканированный, цифровой, гибридный и т. д.).

Поиск

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

Поиск на одной странице, по всему документу или сериализация совпадений на странице в JSON.

Рендеринг

RenderedImage renderPage(int pageIndex, [int format = 0])
RenderedImage renderPageZoom(int pageIndex, double zoom, [int format = 0])
RenderedImage renderPageThumbnail(int pageIndex, int size, [int format = 0])
RenderedImage renderPageWithOptions(int pageIndex, {int dpi = 150, int format = 0, double backgroundR = 1.0, double backgroundG = 1.0, double backgroundB = 1.0, double backgroundA = 1.0, bool transparentBackground = false, bool renderAnnotations = true, int jpegQuality = 90})
RenderedImage renderPageWithOptionsEx(int pageIndex, {int dpi = 150, int format = 0, double backgroundR = 1.0, double backgroundG = 1.0, double backgroundB = 1.0, double backgroundA = 1.0, bool transparentBackground = false, bool renderAnnotations = true, int jpegQuality = 90, List<String> excludedLayers = const []})
RenderedImage renderPageRegion(int pageIndex, double cropX, double cropY, double cropWidth, double cropHeight, [int format = 0])
RenderedImage renderPageFit(int pageIndex, int width, int height, [int format = 0])
RenderedImage renderPageRaw(int pageIndex, [int dpi = 150])
int estimateRenderTime(int pageIndex)
  • renderPage — отрендерить страницу в RenderedImage (format 0=PNG, 1=JPEG).
  • renderPageZoom — рендеринг с коэффициентом масштабирования.
  • renderPageThumbnail — рендеринг миниатюры, вписанной в size пикселей.
  • renderPageWithOptions — полный набор RenderOptions (dpi, фон, аннотации, качество JPEG).
  • renderPageWithOptionsEx — добавляет подавление именованных слоёв OCG через excludedLayers.
  • renderPageRegion — рендеринг прямоугольной области.
  • renderPageFit — рендеринг с вписыванием в width×height с сохранением соотношения сторон.
  • renderPageRaw — рендеринг в необработанный буфер RGBA8888 с предумноженной альфой при заданном dpi.
  • estimateRenderTime — оценка времени рендеринга (мс) для страницы.

Геометрия и элементы страницы

double pageWidth(int pageIndex)
double pageHeight(int pageIndex)
int pageRotation(int pageIndex)
ElementList pageElements(int pageIndex)
Page page(int index)
  • pageWidth / pageHeight — размеры страницы в точках PDF.
  • pageRotation — поворот страницы в градусах.
  • pageElements — элементы разметки страницы в виде ElementList.
  • page — лёгкое представление Page для последовательного постраничного извлечения.

OCR

bool pageNeedsOcr(int pageIndex)
String ocrExtractText(int pageIndex, [OcrEngine? engine])
  • pageNeedsOcr — является ли страница отсканированной/гибридной и требует ли OCR.
  • ocrExtractText — извлечение текста через OCR; engine может быть null для извлечения только нативными средствами.

Проверка соответствия и конвертация

PdfAResults validatePdfA(int level)
UaResults validatePdfUa(int level)
PdfXResults validatePdfX(int level)
bool convertToPdfA(int level)
  • validatePdfA / validatePdfUa / validatePdfX — проверка на соответствие PDF/A, доступности PDF/UA или PDF/X.
  • convertToPdfA — преобразование этого документа на месте в PDF/A заданного уровня.

Экспорт в Office

Uint8List toDocx()
Uint8List toPptx()
Uint8List toXlsx()
Uint8List sourceBytes()
  • toDocx / toPptx / toXlsx — экспорт документа в байты DOCX/PPTX/XLSX.
  • sourceBytes — исходные байты, из которых был загружен этот документ.

Удаление колонтитулов и артефактов

int eraseHeader(int page)
int eraseFooter(int page)
int eraseArtifacts(int page)
int removeHeaders([double threshold = 0.5])
int removeFooters([double threshold = 0.5])
int removeArtifacts([double threshold = 0.5])
  • eraseHeader / eraseFooter / eraseArtifacts — удалить верхний колонтитул, нижний колонтитул или помеченные артефакты на странице; возвращает количество удалённых элементов.
  • removeHeaders / removeFooters / removeArtifacts — удалить повторяющиеся элементы оформления по всему документу, используя порог обнаружения.

Формы

List<FormField> getFormFields()
Uint8List exportFormDataToBytes([int formatType = 0])
void importFormData(String dataPath)
bool importFormFromFile(String filename)
  • getFormFields — интерактивные поля AcroForm.
  • exportFormDataToBytes — экспорт данных формы (formatType 0=FDF, 1=XFDF, 2=JSON).
  • importFormData — импорт данных формы из пути к файлу FDF/XFDF/JSON.
  • importFormFromFile — импорт значений полей из файла; возвращает признак того, было ли что-либо импортировано.

Структура и метаданные документа

String getOutline()
String getPageLabels()
String getXmpMetadata()
bool hasXfa()
String planSplitByBookmarks([String optionsJson = ''])
  • getOutline — оглавление документа (закладки) в виде JSON.
  • getPageLabels — диапазоны меток страниц в виде JSON.
  • getXmpMetadata — метаданные XMP (XML), если присутствуют.
  • hasXfa — содержит ли документ форму XFA.
  • planSplitByBookmarks — построить план разбиения по закладкам в виде JSON.

Цифровые подписи

int sign(Certificate certificate, {String reason = '', String location = ''})
int getSignatureCount()
SignatureInfo getSignature(int index)
int verifyAllSignatures()
bool hasTimestamp()
Dss getDss()
  • sign — поставить цифровую подпись на документе с помощью Certificate.
  • getSignatureCount — количество имеющихся подписей.
  • getSignature — объект SignatureInfo по индексу.
  • verifyAllSignatures — проверка всех подписей (агрегированный статус).
  • hasTimestamp — несёт ли какая-либо подпись метку времени.
  • getDss — хранилище безопасности документа (Dss).

Жизненный цикл

void close()

Немедленно освободить нативный дескриптор (идемпотентно).

Page

Лёгкое представление одной страницы (с отсчётом от нуля), возвращаемое методом PdfDocument.page(index). Хранит сильную ссылку на свой документ и делегирует постраничным методам документа.

Член Тип Описание
index int Индекс страницы с отсчётом от нуля 
String text()
String markdown()
String html()
String plainText()

Извлечённый текст, Markdown, HTML или обычный текст для этой страницы.

Pdf

PDF, созданный (или загруженный) для простого процесса сборки/сохранения.

Фабрики

static Pdf fromMarkdown(String md)
static Pdf fromHtml(String html)
static Pdf fromText(String text)
static Pdf fromImage(String path)
static Pdf fromImageBytes(Uint8List data)
static Pdf fromHtmlCss(String html, String css, [Uint8List? fontBytes])
static Pdf fromHtmlCssWithFonts(String html, String css, List<String> families, List<Uint8List> fonts)
  • fromMarkdown / fromHtml / fromText — создать PDF из Markdown, HTML или обычного текста.
  • fromImage / fromImageBytes — обернуть файл изображения или байты изображения в одностраничный PDF.
  • fromHtmlCss — собрать из HTML + CSS с одним необязательным встроенным шрифтом.
  • fromHtmlCssWithFonts — собрать из HTML + CSS с параллельным каскадом шрифтов families/fonts.

Методы

int get pageCount
void save(String path)
Uint8List toBytes()
void close()
  • pageCount — количество страниц через точку входа pdf_get_page_count.
  • save — сохранить в файл.
  • toBytes — содержимое PDF в виде байтов.
  • close — освободить нативный дескриптор (идемпотентно).

DocumentEditor

Открытый PDF для редактирования на месте: операции со страницами, метаданные, формы, редактирование (редакция), сведение и зашифрованное сохранение.

Конструкторы

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

Сведения и метаданные документа

int get pageCount
PdfVersion get version
bool isModified()
String getSourcePath()
String getProducer()
void setProducer(String value)
String getCreationDate()
void setCreationDate(String dateStr)
  • isModified — есть ли несохранённые изменения.
  • getSourcePath — путь, из которого был открыт редактор.
  • getProducer / setProducer — поле метаданных Producer.
  • getCreationDate / setCreationDate — поле метаданных CreationDate.

Операции со страницами

void deletePage(int pageIndex)
void movePage(int from, int to)
void rotatePageBy(int page, int degrees)
void rotateAllPages(int degrees)
void setPageRotation(int page, int degrees)
int getPageRotation(int page)
void cropMargins(double left, double right, double top, double bottom)
Bbox getPageCropBox(int page)
void setPageCropBox(int page, Bbox box)
Bbox getPageMediaBox(int page)
void setPageMediaBox(int page, Bbox box)
  • deletePage / movePage — удалить или переупорядочить страницы.
  • rotatePageBy — дополнительный (накопительный) поворот; rotateAllPages — относительный поворот всех страниц; setPageRotation — абсолютный; getPageRotation — текущий.
  • cropMargins — обрезать поля на каждой странице.
  • getPageCropBox / setPageCropBox / getPageMediaBox / setPageMediaBox — чтение/запись CropBox/MediaBox.

Редактирование (редакция) и стирание

void applyAllRedactions()
void applyPageRedactions(int page)
void eraseRegion(int page, double x, double y, double w, double h)
void eraseRegions(int page, List<List<double>> rects)
void clearEraseRegions(int page)
bool isPageMarkedForRedaction(int page)
void unmarkPageForRedaction(int page)
void redactionAdd(int page, double x1, double y1, double x2, double y2, {double r = 0.0, double g = 0.0, double b = 0.0})
int redactionCount(int page)
int redactionApply({bool scrubMetadata = false, double r = 0.0, double g = 0.0, double b = 0.0})
int redactionScrubMetadata()
  • applyAllRedactions / applyPageRedactions — применить поставленные в очередь редакции.
  • eraseRegion / eraseRegions / clearEraseRegions — стереть один или несколько прямоугольников либо очистить ожидающие прямоугольники стирания.
  • isPageMarkedForRedaction / unmarkPageForRedaction — запросить/снять пометку страницы на редакцию.
  • redactionAdd — поставить в очередь прямоугольник редакции с цветом заливки наложения.
  • redactionCount — количество поставленных в очередь областей редакции для страницы.
  • redactionApply — необратимо применить все редакции; возвращает количество удалённых глифов.
  • redactionScrubMetadata — удалить метаданные / JavaScript / встроенные файлы; возвращает количество удалённых конструкций.

Сведение (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 — свести все поля формы либо те, что находятся на одной странице.
  • flattenAnnotations / flattenAllAnnotations — свести аннотации на странице или по всему документу.
  • flattenWarningsCount / flattenWarning — предупреждения от последнего сохранения со сведением.
  • isPageMarkedForFlatten / unmarkPageForFlatten — запросить/снять пометку страницы на сведение.

Формы

void setFormFieldValue(String name, String value)
void importFdfBytes(Uint8List data)
void importXfdfBytes(Uint8List data)
  • setFormFieldValue — задать значение поля по имени.
  • importFdfBytes / importXfdfBytes — импортировать значения AcroForm из байтов FDF/XFDF.

Слияние / конвертация / встраивание / извлечение

void mergeFrom(String sourcePath)
void mergeFromBytes(Uint8List data)
void convertToPdfA(int level)
void embedFile(String name, Uint8List data)
Uint8List extractPagesToBytes(List<int> pages)
  • mergeFrom / mergeFromBytes — добавить страницы из PDF на диске или в памяти.
  • convertToPdfA — преобразовать на месте в PDF/A (уровень 0=A1b … 7=A3u).
  • embedFile — присоединить именованный файл.
  • extractPagesToBytes — извлечь подмножество страниц в новый PDF в памяти.

Штрихкоды

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

Нанести сгенерированный BarcodeImage на страницу в заданном прямоугольнике.

Сохранение

void save(String path)
Uint8List saveToBytes()
Uint8List saveToBytesWithOptions(bool compress, bool garbageCollect, bool linearize)
void saveEncrypted(String path, String userPassword, String ownerPassword)
Uint8List saveEncryptedToBytes(String userPassword, String ownerPassword)
void close()
  • save / saveToBytes — сохранить в файл или в буфер байтов.
  • saveToBytesWithOptions — сохранить с явными параметрами сжатия / сборки мусора / линеаризации.
  • saveEncrypted / saveEncryptedToBytes — сохранение с шифрованием AES-256 в файл или в байты.
  • close — освободить нативный дескриптор (идемпотентно).

DocumentBuilder

Текучий (fluent) построитель для сборки совершенно нового PDF-документа.

Создание

static DocumentBuilder create()

Метаданные (текучий стиль)

DocumentBuilder setTitle(String value)
DocumentBuilder setAuthor(String value)
DocumentBuilder setSubject(String value)
DocumentBuilder setKeywords(String value)
DocumentBuilder setCreator(String value)
DocumentBuilder onOpen(String script)
DocumentBuilder language(String lang)
DocumentBuilder taggedPdfUa1()
DocumentBuilder roleMap(String custom, String standard)
DocumentBuilder registerEmbeddedFont(String name, EmbeddedFont font)
  • setTitle/setAuthor/setSubject/setKeywords/setCreator — метаданные документа.
  • onOpen — JavaScript, выполняемый при открытии документа.
  • language — язык документа.
  • taggedPdfUa1 — включить размеченный режим PDF/UA-1.
  • roleMap — сопоставить пользовательский тип структуры со стандартным типом PDF.
  • registerEmbeddedFont — зарегистрировать шрифт под именем (при успехе потребляет EmbeddedFont).

Страницы

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

Открыть страницу A4, US Letter или произвольного размера в виде PageBuilder.

Сборка / сохранение

Uint8List build()
void save(String path)
void saveEncrypted(String path, String userPassword, String ownerPassword)
Uint8List toBytesEncrypted(String userPassword, String ownerPassword)
void close()
  • build — собрать PDF и вернуть его байты.
  • save — собрать и сохранить по пути.
  • saveEncrypted / toBytesEncrypted — сборка с шифрованием AES-256 в файл или в байты.
  • close — освободить нативный дескриптор (идемпотентно).

PageBuilder

Текучий построитель для одной страницы, возвращаемый методами DocumentBuilder.page / letterPage / a4Page. Каждая операция возвращает this для цепочечных вызовов. Вызовите done(), чтобы зафиксировать страницу, или close(), чтобы отбросить её.

Текст и разметка

PageBuilder font(String name, double size)
PageBuilder at(double x, double y)
PageBuilder text(String value)
PageBuilder heading(int level, String value)
PageBuilder paragraph(String value)
PageBuilder space(double points)
PageBuilder horizontalRule()
PageBuilder columns(int columnCount, double gapPt, String value)
PageBuilder inline(String value)
PageBuilder inlineBold(String value)
PageBuilder inlineItalic(String value)
PageBuilder inlineColor(double r, double g, double b, String value)
PageBuilder newline()
PageBuilder footnote(String refMark, String noteText)
PageBuilder textInRect(double x, double y, double w, double h, String value, int align)
PageBuilder newPageSameSize()
  • font / at — задать активный шрифт/размер и позицию курсора.
  • text / heading / paragraph — вывести текст, заголовок заданного уровня или абзац с переносом строк.
  • space / horizontalRule / newline — вертикальный отступ, горизонтальная линия, перевод строки.
  • columns — многоколоночный текст с промежутком.
  • inline / inlineBold / inlineItalic / inlineColor — встроенные фрагменты текста.
  • footnote — знак сноски плюс текст примечания.
  • textInRect — текст, размещённый внутри прямоугольника с кодом выравнивания (0=влево, 1=по центру, 2=вправо).
  • newPageSameSize — начать новую страницу того же размера.

Ссылки

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

Прикрепить к последнему содержимому ссылку на URL, внутреннюю ссылку на страницу, ссылку на именованную точку назначения или ссылку JavaScript.

Действия и скрипты полей

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

Действия при открытии/закрытии страницы и скрипты полей AcroForm для нажатия клавиш / форматирования / валидации / вычисления.

Текстовая разметка

PageBuilder highlight(double r, double g, double b)
PageBuilder underline(double r, double g, double b)
PageBuilder strikeout(double r, double g, double b)
PageBuilder squiggly(double r, double g, double b)

Аннотации разметки поверх последнего текста заданным цветом RGB.

Аннотации / водяной знак / штамп

PageBuilder stickyNote(String value)
PageBuilder stickyNoteAt(double x, double y, String value)
PageBuilder watermark(String value)
PageBuilder watermarkConfidential()
PageBuilder watermarkDraft()
PageBuilder stamp(String typeName)
PageBuilder freetext(double x, double y, double w, double h, String value)
  • stickyNote / stickyNoteAt — заметка-стикер в позиции курсора или в явной позиции.
  • watermark / watermarkConfidential / watermarkDraft — произвольный или предустановленные водяные знаки.
  • stamp — именованный штамп.
  • freetext — аннотация со свободным текстом в прямоугольнике.

Изображения и штрихкоды

PageBuilder image(Uint8List bytes, double x, double y, double w, double h)
PageBuilder imageArtifact(Uint8List bytes, double x, double y, double w, double h)
PageBuilder imageWithAlt(Uint8List bytes, double x, double y, double w, double h, String altText)
PageBuilder barcode1d(int barcodeType, String data, double x, double y, double w, double h)
PageBuilder barcodeQr(String data, double x, double y, double size)
  • image — поместить изображение; imageArtifact — поместить несодержательное (артефактное) изображение; imageWithAlt — поместить изображение с альтернативным текстом для доступности.
  • barcode1d / barcodeQr — нарисовать 1D-штрихкод или QR-код прямо на странице.

Векторная графика

PageBuilder rect(double x, double y, double w, double h)
PageBuilder filledRect(double x, double y, double w, double h, double r, double g, double b)
PageBuilder line(double x1, double y1, double x2, double y2)
PageBuilder strokeRect(double x, double y, double w, double h, double width, double r, double g, double b)
PageBuilder strokeLine(double x1, double y1, double x2, double y2, double width, double r, double g, double b)
PageBuilder strokeRectDashed(double x, double y, double w, double h, double width, double r, double g, double b, List<double> dashArray, [double phase = 0])
PageBuilder strokeLineDashed(double x1, double y1, double x2, double y2, double width, double r, double g, double b, List<double> dashArray, [double phase = 0])

Заполненные и обведённые прямоугольники и линии, включая штриховые обводки с массивом штрихов и фазой.

Поля формы

PageBuilder textField(String name, double x, double y, double w, double h, [String? defaultValue])
PageBuilder checkbox(String name, double x, double y, double w, double h, bool checked)
PageBuilder comboBox(String name, double x, double y, double w, double h, List<String> options, int count, [String? selected])
PageBuilder radioGroup(String name, List<String> values, List<double> xs, List<double> ys, List<double> ws, List<double> hs, int count, [String? selected])
PageBuilder pushButton(String name, double x, double y, double w, double h, String caption)
PageBuilder signatureField(String name, double x, double y, double w, double h)

Добавить виджеты AcroForm: текстовые поля, флажки, комбинированные списки, группы переключателей, кнопки и поля подписи.

Таблицы

PageBuilder table(int nCols, List<double> widths, List<int> aligns, int nRows, List<String> cellStrings, bool hasHeader)
PageBuilder streamingTableBegin(List<String> headers, List<double> widths, List<int> aligns, bool repeatHeader)
PageBuilder streamingTableBeginV2(List<String> headers, List<double> widths, List<int> aligns, bool repeatHeader, {int mode = 0, int sampleRows = 0, double minColWidthPt = 0, double maxColWidthPt = 0, int maxRowspan = 1})
PageBuilder streamingTablePushRow(List<String> cells)
PageBuilder streamingTablePushRowV2(List<String> cells, List<int> rowspans)
PageBuilder streamingTableFlush()
PageBuilder streamingTableFinish()
PageBuilder streamingTableSetBatchSize(int batchSize)
int streamingTableBatchCount()
int streamingTablePendingRowCount()
  • table — буферизовать статическую таблицу в порядке по строкам.
  • streamingTableBegin / streamingTableBeginV2 — начать потоковую таблицу (v2 добавляет режим ширины столбцов, выборочные строки, минимальную/максимальную ширину столбцов и объединение строк).
  • streamingTablePushRow / streamingTablePushRowV2 — добавить строку (v2 с объединением строк для каждой ячейки).
  • streamingTableFlush / streamingTableFinish — сбросить ожидающие строки / закрыть таблицу.
  • streamingTableSetBatchSize — количество строк, буферизуемых перед каждым сбросом.
  • streamingTableBatchCount / streamingTablePendingRowCount — количество сброшенных пакетов / ожидающих строк.

Жизненный цикл

void done()
void close()
  • done — зафиксировать буферизованные операции в родительском построителе (потребляет дескриптор).
  • close — отбросить страницу и освободить дескриптор (идемпотентно).

EmbeddedFont

Загруженный шрифт TTF/OTF для встраивания через DocumentBuilder.registerEmbeddedFont.

static EmbeddedFont fromFile(String path)
static EmbeddedFont fromBytes(Uint8List data, [String? name])
void close()
  • fromFile — загрузить шрифт из пути к файлу.
  • fromBytes — загрузить из байтов; name по умолчанию принимает PostScript-имя шрифта.
  • close — освободить нативный дескриптор (идемпотентно).

RenderedImage

Растеризованное изображение страницы, возвращаемое методом PdfDocument.renderPage и аналогичными.

int get width
int get height
Uint8List get data
void save(String path)
void close()
  • width / height — размеры изображения в пикселях.
  • data — закодированные байты изображения (например, PNG), скопированные в Dart.
  • save — записать закодированное изображение по пути.
  • close — освободить нативный дескриптор (идемпотентно).

ElementList

Элементы разметки страницы, создаваемые методом PdfDocument.pageElements.

int get count
Element operator [](int index)
List<Element> toList()
String toJson()
void close()
  • count — количество элементов.
  • operator [] — прочитать элемент по индексу.
  • toList — все элементы в виде списка.
  • toJson — весь список, сериализованный в JSON.
  • close — освободить нативный дескриптор (идемпотентно).

BarcodeImage

Сгенерированный 1D-штрихкод или QR-код. Наносится на страницу с помощью DocumentEditor.addBarcodeToPage.

static BarcodeImage qr(String data, {int errorCorrection = 0, int sizePx = 256})
static BarcodeImage barcode(String data, int format, {int sizePx = 256})
String get data
int get format
double get confidence
Uint8List imagePng({int sizePx = 256})
String svg({int sizePx = 256})
void close()
  • qr — сгенерировать QR-код с уровнем коррекции ошибок и размером в пикселях.
  • barcode — сгенерировать 1D-штрихкод в заданном коде формата.
  • data / format / confidence — закодированные данные, код формата и уверенность распознавания.
  • imagePng / svg — закодировать как байты PNG или строку SVG.
  • close — освободить нативный дескриптор (идемпотентно).

OcrEngine

Движок OCR на основе файлов моделей детекции/распознавания, передаваемый в PdfDocument.ocrExtractText.

static OcrEngine create(String detModelPath, String recModelPath, String dictPath)
void close()
  • create — создать движок из путей к модели детекции, модели распознавания и файлу словаря.
  • close — освободить нативный дескриптор (идемпотентно).

Renderer

Переиспользуемый рендерер страниц, настроенный на фиксированные DPI/формат/качество.

static Renderer create({int dpi = 150, int format = 0, int quality = 90, bool antiAlias = true})
void close()
  • create — создать рендерер (format 0=PNG, 1=JPEG; quality 1…100).
  • close — освободить нативный дескриптор (идемпотентно).

Certificate

Учётные данные для подписи / сертификат X.509, используемый точками входа подписи.

static Certificate loadFromBytes(Uint8List bytes, String password)
static Certificate loadFromPem(String certPem, String keyPem)
Pointer<Void> get handle
String get subject
String get issuer
String get serial
CertificateValidity get validity
bool isValid()
void close()
  • loadFromBytes — загрузить из буфера PKCS#12 (.p12/.pfx) с паролем.
  • loadFromPem — загрузить из строк PEM-сертификата и закрытого ключа.
  • handle — необработанный нативный дескриптор (для продвинутого использования / interop).
  • subject / issuer / serial — отличительные имена и серийный номер.
  • validity — интервал notBefore/notAfter в виде CertificateValidity.
  • isValid — действителен ли сертификат в настоящее время.
  • close — освободить нативный дескриптор (идемпотентно).

Timestamp

Токен метки времени RFC 3161.

static Timestamp parse(Uint8List bytes)
Uint8List get token
Uint8List get messageImprint
int get time
String get serial
String get tsaName
String get policyOid
int get hashAlgorithm
bool verify()
void close()
  • parse — разобрать TimeStampToken в DER-кодировке (или «голый» TSTInfo).
  • token / messageImprint — полный токен и байты хешированного отпечатка сообщения.
  • time — время метки (секунды эпохи Unix).
  • serial / tsaName / policyOid / hashAlgorithm — серийный номер токена, имя TSA, OID политики и код алгоритма хеширования.
  • verify — криптографически проверить токен.
  • close — освободить нативный дескриптор (идемпотентно).

TsaClient

Клиент TSA (центра меток времени) 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 — создать клиент для URL TSA с необязательной базовой аутентификацией и параметрами запроса.
  • requestTimestamp — запросить метку времени для необработанных данных (клиент хеширует их сам).
  • requestTimestampHash — запросить метку времени для заранее вычисленного хеша.
  • close — освободить нативный дескриптор (идемпотентно).

SignatureInfo

Информация о цифровой подписи, встроенной в PDF, из 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 — принять необработанный нативный дескриптор (для продвинутого использования / interop).
  • signerName / signingReason / signingLocation / signingTime — метаданные подписавшего.
  • certificate — сертификат подписавшего (Certificate).
  • padesLevel — код уровня базового профиля PAdES или -1, если это не PAdES.
  • hasTimestamp / timestamp — наличие встроенной метки времени и сам объект Timestamp.
  • addTimestamp — присоединить метку времени к этой подписи.
  • verify — криптографическая проверка атрибутов подписавшего (1 действительна / 0 недействительна / -1 неизвестно).
  • verifyDetached — сквозная проверка по полным байтам PDF (1 действительна / 0 недействительна / -1 неизвестно).
  • close — освободить нативный дескриптор (идемпотентно).

Dss

Хранилище безопасности документа /DSS (document security store), из 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 — принять необработанный дескриптор DSS (для продвинутого использования / interop).
  • certCount / crlCount / ocspCount / vriCount — количество сертификатов, CRL, ответов OCSP и записей VRI.
  • getCert / getCrl / getOcsp — DER-байты сертификата / CRL / ответа OCSP по индексу.
  • close — освободить нативный дескриптор (идемпотентно).

PdfAResults

Результаты валидации PDF/A из PdfDocument.validatePdfA.

bool isCompliant()
List<String> errors()
List<String> warnings()
void close()
  • isCompliant — соответствует ли документ стандарту PDF/A.
  • errors / warnings — сообщения об ошибках и предупреждениях валидации.
  • close — освободить нативный дескриптор (идемпотентно).

UaResults

Результаты валидации доступности PDF/UA из PdfDocument.validatePdfUa.

bool isAccessible()
List<String> errors()
List<String> warnings()
UaStats uaStats()
void close()
  • isAccessible — доступен ли документ по стандарту PDF/UA.
  • errors / warnings — сообщения об ошибках и предупреждениях доступности.
  • uaStats — статистика элементов, собранная в ходе валидации.
  • close — освободить нативный дескриптор (идемпотентно).

PdfXResults

Результаты валидации PDF/X из PdfDocument.validatePdfX.

bool isCompliant()
List<String> errors()
void close()
  • isCompliant — соответствует ли документ стандарту PDF/X.
  • errors — сообщения об ошибках валидации.
  • close — освободить нативный дескриптор (идемпотентно).

Функции верхнего уровня

Эти функции уровня библиотеки находятся в пространстве имён pdf_oxide.

Слияние и метка времени

Uint8List pdfMerge(List<String> paths)
Uint8List addTimestamp(Uint8List pdf, int sigIndex, String tsaUrl)
  • pdfMerge — объединить PDF по заданным путям (по порядку) в один PDF; возвращает его байты.
  • addTimestamp — применить метку времени RFC 3161 к подписи, обратившись к TSA; возвращает байты PDF с меткой времени.

Подписание

Uint8List signBytes(Uint8List pdf, Certificate cert, {String reason = '', String location = ''})
Uint8List signBytesPades(Uint8List pdf, Certificate cert, int level, {String? tsaUrl, String reason = '', String location = '', List<Uint8List> certs = const [], List<Uint8List> crls = const [], List<Uint8List> ocsps = const []})
Uint8List signBytesPadesOpts(Uint8List pdf, Certificate cert, int level, {String? tsaUrl, String reason = '', String location = '', List<Uint8List> certs = const [], List<Uint8List> crls = const [], List<Uint8List> ocsps = const []})
  • signBytes — подписать необработанные байты PDF сертификатом; возвращает подписанные байты.
  • signBytesPades — подписать на базовом уровне PAdES (0=B-B, 1=B-T, 2=B-LT); tsaUrl обязателен для уровня ≥ 1, а certs/crls/ocsps несут материал отзыва для B-LT.
  • signBytesPadesOpts — вариант signBytesPades со структурой параметров и идентичным поведением.

Логирование

void setLogLevel(int level)
int getLogLevel()

Установить/получить глобальный уровень логирования библиотеки (0=Off, 1=Error, 2=Warn, 3=Info, 4=Debug, 5=Trace).

Криптография / FIPS

String cryptoActiveProvider()
String cryptoCbom()
String cryptoInventory()
String cryptoPolicy()
int cryptoFipsAvailable()
int cryptoUseFips()
int cryptoSetPolicy(String spec)
  • cryptoActiveProvider — имя активного криптографического провайдера.
  • cryptoCbom — криптографическая спецификация компонентов (CBOM) в виде JSON.
  • cryptoInventory — криптографическая инвентаризация в виде JSON.
  • cryptoPolicy — активная криптографическая политика в виде JSON.
  • cryptoFipsAvailable — доступен ли провайдер, валидированный по FIPS (ненулевое значение = да).
  • cryptoUseFips — переключиться на провайдер, валидированный по FIPS; возвращает статус.
  • cryptoSetPolicy — задать криптографическую политику из строки спецификации; возвращает статус.

Модели и глобальная конфигурация

String modelManifest()
int prefetchAvailable()
String prefetchModels(String languagesCsv)
int setMaxOpsPerStream(int limit)
int setPreserveUnmappedGlyphs(int preserve)
  • modelManifest — встроенный манифест моделей в виде JSON.
  • prefetchAvailable — доступна ли предзагрузка моделей в этой сборке.
  • prefetchModels — предзагрузить модели OCR/разметки для языков, перечисленных через запятую; возвращает отчёт в JSON.
  • setMaxOpsPerStream — задать глобальный предел операторов на один поток содержимого; возвращает предыдущее значение.
  • setPreserveUnmappedGlyphs — переключить сохранение несопоставленных глифов; возвращает предыдущее значение.

Обработка ошибок

PdfOxideError

Все коды ошибок C ABI (кроме успешного) выбрасываются как PdfOxideError.

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

Вызов метода на дескрипторе после close() выбрасывает Dart-исключение StateError. EmbeddedFont.fromBytes с некорректными данными шрифта, Certificate.loadFromBytes с некорректным PKCS#12 и PdfDocument.open для отсутствующего файла — все они порождают PdfOxideError.

import 'package:pdf_oxide/pdf_oxide.dart';

void main() {
  try {
    final doc = PdfDocument.open('input.pdf');
    print(doc.extractText(0));
    doc.close();
  } on PdfOxideError catch (e) {
    print('PDF error: $e');  // PdfOxideError: <op> failed (error code <code>)
  }
}

Типы значений

Простые классы данных, возвращаемые методами извлечения и инспекции.

PdfVersion

Поле Тип Описание
major int Старшая версия
minor int Младшая версия

Bbox

Ограничивающий прямоугольник, выровненный по осям, в точках пользовательского пространства PDF.

Поле Тип Описание
x, y double Левый нижний угол (начало координат)
width, height double Размер прямоугольника

Char

Поле Тип Описание
character int Кодовая точка Unicode
bbox Bbox Ограничивающий прямоугольник глифа
fontName String PostScript-имя шрифта
fontSize double Размер шрифта в точках

Word

Поле Тип Описание
text String Текст слова
bbox Bbox Ограничивающий прямоугольник
fontName String Имя шрифта
fontSize double Размер шрифта
bold bool Является ли полужирным

TextLine

Поле Тип Описание
text String Текст строки
bbox Bbox Ограничивающий прямоугольник
wordCount int Количество слов

Table

Член Тип Описание
rowCount int Количество строк
colCount int Количество столбцов
hasHeader bool Присутствует ли строка заголовка
cell(int row, int col) String Текст ячейки с отсчётом от 0

Font

Поле Тип Описание
name String Имя шрифта
type String Тип шрифта
encoding String Кодировка
embedded bool Является ли встроенным
subset bool Является ли подмножеством

Image

Поле Тип Описание
width, height int Размеры в пикселях
bitsPerComponent int Бит на компонент
format String Формат изображения
colorspace String Цветовое пространство
data Uint8List Необработанные байты изображения

Annotation

Поле Тип Описание
type String Тип аннотации
subtype String Подтип аннотации
content String Текстовое содержимое
author String Автор
rect Bbox Позиция
borderWidth double Ширина рамки

Path

Поле Тип Описание
bbox Bbox Ограничивающий прямоугольник
strokeWidth double Ширина обводки
hasStroke bool Является ли обведённым
hasFill bool Является ли заполненным
operationCount int Количество операций пути

SearchResult

Поле Тип Описание
text String Найденный текст
page int Индекс страницы с отсчётом от нуля
bbox Bbox Ограничивающий прямоугольник совпадения

FormField

Поле Тип Описание
name String Полное (квалифицированное) имя поля
value String Текущее значение
type String Тип поля (Tx, Btn, Ch, Sig)
readonly bool Является ли только для чтения
required bool Является ли обязательным

QuadPoint

Квадрант аннотации-выделения (четыре угловые точки): x1, y1, x2, y2, x3, y3, x4, y4 (double).

AnnotationDetails

Поле Тип Описание
type, subtype, content String Тип/подтип и содержимое аннотации
rect Bbox Позиция
color int Упакованный цвет ARGB
creationDate, modificationDate int Секунды эпохи Unix (0, если отсутствует)
hidden, markedDeleted, printable, readOnly bool Флаги аннотации
linkUri String Целевой URI ссылки (иначе пустая строка)
iconName String Имя иконки текстовой аннотации (иначе пустая строка)
quadPoints List<QuadPoint> Квадранты выделения (иначе пусто)

CertificateValidity

Поле Тип Описание
notBefore int Время начала действия (секунды эпохи Unix)
notAfter int Время окончания действия (секунды эпохи Unix)

UaStats

Поле Тип Описание
structElements int Элементы структуры
images int Изображения
tables int Таблицы
forms int Поля формы
annotations int Аннотации
pages int Страницы

Element

Поле Тип Описание
type String Тип элемента (например, Text, Image, Table)
text String Текстовое содержимое (может быть пустым)
rect Bbox Ограничивающий прямоугольник

Полный пример

import 'dart:io';
import 'package:pdf_oxide/pdf_oxide.dart';

void main() {
  // --- Creation ---
  final pdf = Pdf.fromMarkdown('# Report\n\nGenerated by PDF Oxide.');
  pdf.save('report.pdf');
  pdf.close();

  // --- Builder ---
  final db = DocumentBuilder.create()..setTitle('Invoice');
  final page = db.letterPage();
  page
      .font('Helvetica', 14)
      .heading(1, 'Invoice')
      .paragraph('Thank you for your business.')
      .done();
  File('invoice.pdf').writeAsBytesSync(db.build());
  db.close();

  // --- Extraction ---
  final doc = PdfDocument.open('report.pdf');
  print('Pages: ${doc.pageCount}');
  for (var i = 0; i < doc.pageCount; i++) {
    print('Page $i: ${doc.extractText(i).length} chars');
  }
  for (final word in doc.extractWords(0)) {
    print('${word.text} @ ${word.bbox}');
  }

  // --- Search ---
  for (final hit in doc.searchAll('PDF Oxide', false)) {
    print('Found "${hit.text}" on page ${hit.page}');
  }

  // --- Rendering ---
  final img = doc.renderPage(0);
  img.save('page0.png');
  img.close();
  doc.close();

  // --- Editing ---
  final ed = DocumentEditor.open('report.pdf');
  ed.rotateAllPages(90);
  ed.setProducer('PDF Oxide');
  ed.save('rotated.pdf');
  ed.close();
}

Other Language Bindings

PDF Oxide предоставляет нативные привязки для всех основных экосистем: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, R, Julia, Zig, Scala, Clojure, Objective-C, и Elixir.

Дальнейшие шаги