Skip to content
PDF Oxide

Довідник API для Dart

PDF Oxide постачає ідіоматичні прив’язки для Dart/Flutter, побудовані на dart:ffi поверх нативного C ABI. Пакет завантажує наперед скомпільовану libpdf_oxide.{so,dylib,dll} під час виконання й відкриває повну поверхню API — видобування, редагування, створення, рендеринг, форми, 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 — чи це тегований 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 — відрендерити у сирий буфер premultiplied 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 / вбудовані файли; повертає кількість видалених конструкцій.

Сплощення

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

Метадані (fluent)

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

Плавний (fluent) будівник для однієї сторінки, який повертає 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)

Дії при відкритті/закритті сторінки та скрипти keystroke/format/validate/calculate для полів 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 — намалювати одновимірний штрихкод або 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

Згенерований одновимірний штрихкод або 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 — згенерувати одновимірний штрихкод у заданому коді формату.
  • 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 (сховище безпеки документа), з 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 Текст комірки (з нумерацією від нуля)

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.

Наступні кроки