Skip to content
PDF Oxide

Початок роботи з PDF Oxide (Kotlin)

PDF Oxide — найшвидша PDF-бібліотека для JVM із вбудованим видобуванням тексту: у середньому 0,8 мс, 100% успішних проходів на 3 830 PDF. Прив’язка для Kotlin — це ідіоматичний, готовий до Android фасад над прив’язкою для Java: вона додає use { } до закриваних дескрипторів і перетворює Java-повернення Optional<T> на nullable-тип T?. Одна бібліотека для видобування, створення та редагування PDF. Ліцензія MIT, в основі — ядро на Rust.

Встановлення

Додайте прив’язку для Kotlin до свого build.gradle.kts. Вона транзитивно підтягує прив’язку для Java, що володіє нативним JNI-мостом:

dependencies {
    implementation("fyi.oxide:pdf-oxide-kotlin:0.3.69")
}

Вимоги: JDK 17+. На Android постачайте нативну libpdf_oxide_jni.so у jniLibs/<abi>/; на десктопній JVM завантажувач знаходить її автоматично (за потреби перевизначте через -Dfyi.oxide.pdf.lib.path=<path>).

Швидкий старт

Зберіть PDF із Markdown, відкрийте його та прочитайте текст назад. Дескриптори Pdf і PdfDocument є AutoCloseable, тож загорніть їх у use { }:

import fyi.oxide.pdf.Pdf
import fyi.oxide.pdf.PdfDocument
import fyi.oxide.pdf.producerOrNull

Pdf.fromMarkdown("# Hello pdf_oxide\n\nThis is a **Kotlin** binding.\n").use { pdf ->
    PdfDocument.open(pdf.save()).use { doc ->
        println("pages:    ${doc.pageCount()}")
        println("producer: ${doc.producerOrNull() ?: "(none)"}")
        println(doc.extractText(0))
    }
}

Pdf.fromMarkdown(String) повертає закриваний білдер Pdf; pdf.save() серіалізує його в ByteArray. PdfDocument.open(ByteArray) відкриває ці дані для читання.

Відкриття PDF

Відкрийте наявний документ із байтів і перегляньте його метадані. producerOrNull() і creatorOrNull() — це nullable-подання Kotlin над Java-гетерами, що повертають Optional:

import fyi.oxide.pdf.PdfDocument
import fyi.oxide.pdf.producerOrNull
import fyi.oxide.pdf.creatorOrNull

PdfDocument.open(pdfBytes).use { doc ->
    println("open:     ${doc.isOpen}")
    println("pages:    ${doc.pageCount()}")
    println("producer: ${doc.producerOrNull() ?: "(none)"}")
    println("creator:  ${doc.creatorOrNull() ?: "(none)"}")
}

Видобування тексту

Видобувайте звичайний текст із будь-якої сторінки за її індексом, що відлічується від нуля, або пройдіться по всіх сторінках циклом:

import fyi.oxide.pdf.PdfDocument

PdfDocument.open(pdfBytes).use { doc ->
    // окрема сторінка
    println(doc.extractText(0))

    // кожна сторінка
    for (i in 0 until doc.pageCount()) {
        println("--- Page ${i + 1} ---")
        println(doc.extractText(i))
    }
}

Елементи сторінки

doc.page(i) повертає PdfPage, що надає структуровану геометрію — слова, рядки, символи, таблиці, зображення та анотації. Кожне слово несе свій текст і обмежувальний прямокутник:

import fyi.oxide.pdf.PdfDocument

PdfDocument.open(pdfBytes).use { doc ->
    val page = doc.page(0)
    println("size: ${page.width()} x ${page.height()}")

    page.words().take(8).forEach { word ->
        println("${word.text()} @ ${word.bbox()}")
    }

    println("lines:       ${page.lines().size}")
    println("chars:       ${page.chars().size}")
    println("tables:      ${page.tables().size}")
    println("images:      ${page.images().size}")
    println("annotations: ${page.annotations().size}")
}

bbox() слова — це BBox із допоміжними методами на кшталт width() і height().

Конвертація в Markdown і HTML

Перетворіть весь документ на Markdown або відрендеріть сторінку в HTML:

import fyi.oxide.pdf.PdfDocument

PdfDocument.open(pdfBytes).use { doc ->
    val markdown = doc.toMarkdown()  // всі сторінки
    println(markdown)

    val html = doc.toHtml()
    println(html)
}

Пошук

Шукайте текст по всьому документу. Кожен збіг надає свій текст через text():

import fyi.oxide.pdf.PdfDocument

PdfDocument.open(pdfBytes).use { doc ->
    val matches = doc.search("configuration")
    matches.forEach { m ->
        println("match: ${m.text()}")
    }
}

Автоматичне видобування

AutoExtractor запускає повний конвеєр видобування одним викликом і повертає AutoResult із текстом плюс опціональними рендерами в Markdown/HTML. Розширення markdownOrNull() / htmlOrNull() перетворюють Java-повернення Optional на nullable-значення:

import fyi.oxide.pdf.PdfDocument
import fyi.oxide.pdf.AutoExtractor
import fyi.oxide.pdf.markdownOrNull
import fyi.oxide.pdf.htmlOrNull

PdfDocument.open(pdfBytes).use { doc ->
    val result = AutoExtractor.of(doc).extractDocument()
    println(result.text())
    result.markdownOrNull()?.let { println(it) }
    result.htmlOrNull()?.let { println(it) }
}

Редагування

DocumentEditor відкриває PDF для структурних змін — наприклад, очищення метаданих перед поширенням — а потім серіалізує результат назад у байти:

import fyi.oxide.pdf.DocumentEditor

DocumentEditor.open(pdfBytes).use { editor ->
    editor.scrubMetadata()
    val cleaned: ByteArray = editor.save()
    println("cleaned: ${cleaned.size} bytes")
}

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