Справочник JavaScript API
PDF Oxide предоставляет WebAssembly-привязки для JavaScript и TypeScript. Npm-пакет pdf-oxide-wasm работает как в Node.js, так и в браузерах.
npm install pdf-oxide-wasm
Для Rust API см. Rust API Reference. Для Python API см. Справочник Python API. Подробности о типах см. в Типы и перечисления.
WasmPdfDocument
Основной класс для открытия, извлечения, редактирования и сохранения PDF.
import { WasmPdfDocument } from "pdf-oxide-wasm";
Конструктор
new WasmPdfDocument(data)
Загрузка PDF-документа из необработанных байтов.
| Параметр | Тип | Описание |
|---|---|---|
data |
Uint8Array |
Содержимое PDF-файла |
Вызывает: Error, если PDF невалиден или не может быть разобран.
const bytes = new Uint8Array(readFileSync("document.pdf"));
const doc = new WasmPdfDocument(bytes);
Базовые операции чтения
pageCount() -> number
Получение количества страниц в документе.
version() -> Uint8Array
Получить версию PDF в формате [major, minor].
const [major, minor] = doc.version();
console.log(`PDF ${major}.${minor}`);
authenticate(password) -> boolean
Расшифровка зашифрованного PDF. Возвращает true при успешной аутентификации.
| Параметр | Тип | Описание |
|---|---|---|
password |
string |
Строка пароля |
hasStructureTree() -> boolean
Проверка, является ли документ тегированным PDF с деревом структуры.
Извлечение текста
extractText(pageIndex) -> string
Извлечение простого текста с одной страницы.
| Параметр | Тип | Описание |
|---|---|---|
pageIndex |
number |
Номер страницы (с нуля) |
const text = doc.extractText(0);
extractAllText() -> string
Извлечение простого текста со всех страниц, разделённых символами перевода страницы.
extractChars(pageIndex) -> Array
Извлечение отдельных символов с точным позиционированием и метаданными шрифтов.
| Параметр | Тип | Описание |
|---|---|---|
pageIndex |
number |
Номер страницы (с нуля) |
Возвращает: Массив объектов с полями:
| Поле | Тип | Описание |
|---|---|---|
char |
string |
The character |
bbox |
{x, y, width, height} |
Ограничивающий прямоугольник |
font_name |
string |
Имя шрифта |
font_size |
number |
Размер шрифта в пунктах |
font_weight |
string |
Насыщенность (Normal, Bold и т.д.) |
is_italic |
boolean |
Флаг курсива |
color |
{r, g, b} |
Цвет RGB (0.0–1.0) |
const chars = doc.extractChars(0);
for (const c of chars) {
console.log(`'${c.char}' at (${c.bbox.x}, ${c.bbox.y})`);
}
extractSpans(pageIndex) -> Array
Извлечение стилизованных текстовых span’ов с метаданными шрифтов.
| Параметр | Тип | Описание |
|---|---|---|
pageIndex |
number |
Номер страницы (с нуля) |
Возвращает: Массив объектов с полями:
| Поле | Тип | Описание |
|---|---|---|
text |
string |
Текстовое содержимое |
bbox |
{x, y, width, height} |
Ограничивающий прямоугольник |
font_name |
string |
Имя шрифта |
font_size |
number |
Размер шрифта в пунктах |
font_weight |
string |
Насыщенность (Normal, Bold и т.д.) |
is_italic |
boolean |
Флаг курсива |
color |
{r, g, b} |
Цвет RGB (0.0–1.0) |
const result = doc.extractPageText(0);
console.log(`Page: ${result.pageWidth}x${result.pageHeight} pt`);
for (const span of result.spans) {
console.log(`'${span.text}' font=${span.fontName} size=${span.fontSize}`);
}
const spans = doc.extractSpans(0);
for (const span of spans) {
console.log(`"${span.text}" size=${span.fontSize}`);
}
Конвертация форматов
toMarkdown(pageIndex, detectHeadings?, includeImages?, includeFormFields?) -> string
Конвертация одной страницы в Markdown.
| Parameter | Type | Default | Описание |
|---|---|---|---|
pageIndex |
number |
– | Номер страницы (с нуля) |
detectHeadings |
boolean |
true |
Определять заголовки from font size |
includeImages |
boolean |
true |
Включать изображения |
includeFormFields |
boolean |
true |
Включать значения полей форм |
toMarkdownAll(detectHeadings?, includeImages?, includeFormFields?) -> string
Конвертация всех страниц в Markdown.
toHtml(pageIndex, preserveLayout?, detectHeadings?, includeFormFields?) -> string
Конвертация одной страницы в HTML.
| Parameter | Type | Default | Описание |
|---|---|---|---|
pageIndex |
number |
– | Номер страницы (с нуля) |
preserveLayout |
boolean |
false |
Сохранять визуальный макет |
detectHeadings |
boolean |
true |
Определять заголовки |
includeFormFields |
boolean |
true |
Включать значения полей форм |
toHtmlAll(preserveLayout?, detectHeadings?, includeFormFields?) -> string
Конвертация всех страниц в HTML.
toPlainText(pageIndex) -> string
Конвертация одной страницы в простой текст.
toPlainTextAll() -> string
Конвертация всех страниц в простой текст.
Поиск
search(pattern, caseInsensitive?, literal?, wholeWord?, maxResults?) -> Array
Поиск текста по всем страницам.
| Parameter | Type | Default | Описание |
|---|---|---|---|
pattern |
string |
– | Шаблон поиска (строка или регулярное выражение) |
caseInsensitive |
boolean |
false |
Регистронезависимый поиск |
literal |
boolean |
false |
Обрабатывать шаблон как литеральную строку |
wholeWord |
boolean |
false |
Сопоставлять только целые слова |
maxResults |
number |
– | Максимальное количество возвращаемых результатов |
Возвращает: Массив объектов с полями:
| Поле | Тип | Описание |
|---|---|---|
page |
number |
Номер страницы |
text |
string |
Найденный текст |
bbox |
object |
Ограничивающий прямоугольник |
start_index |
number |
Начальный индекс в тексте страницы |
end_index |
number |
Конечный индекс в тексте страницы |
searchPage(pageIndex, pattern, caseInsensitive?, literal?, wholeWord?, maxResults?) -> Array
Поиск текста на одной странице.
Информация об изображениях
extractImages(pageIndex) -> Array
Получение метаданных изображений для страницы.
| Поле | Тип | Описание |
|---|---|---|
width |
number |
Ширина изображения в пикселях |
height |
number |
Высота изображения в пикселях |
color_space |
string |
Цветовое пространство (напр. DeviceRGB) |
bits_per_component |
number |
Бит на цветовой канал |
bbox |
object |
Позиция на странице |
extractImageBytes(pageIndex) -> Array
Извлечение необработанных байтов изображений со страницы. Возвращает массив объектов:
| Поле | Тип | Описание |
|---|---|---|
width |
number |
Ширина изображения в пикселях |
height |
number |
Высота изображения в пикселях |
data |
Uint8Array |
Необработанные байты изображения |
format |
string |
Формат изображения |
pageImages(pageIndex) -> Array
Получение имён изображений и границ для операций позиционирования.
| Поле | Тип | Описание |
|---|---|---|
name |
string |
Имя XObject |
bounds |
number[] |
[x, y, width, height] |
matrix |
number[] |
Матрица трансформации [a, b, c, d, e, f] |
Структура документа
getOutline() -> Array | null
Получение закладок / оглавления документа. Возвращает null, если оглавление отсутствует.
getAnnotations(pageIndex) -> Array
Получение метаданных аннотаций (тип, прямоугольник, содержимое и т.д.) для страницы.
extractPaths(pageIndex) -> Array
Получение векторных контуров (линии, кривые, фигуры) со страницы.
pageLabels() -> Array
Получение диапазонов меток страниц. Возвращает массив объектов:
| Поле | Тип | Описание |
|---|---|---|
start_page |
number |
Первая страница в диапазоне |
style |
string |
Стиль нумерации |
prefix |
string |
Префикс метки |
start_value |
number |
Начальный номер |
xmpMetadata() -> object | null
Получение метаданных XMP. Возвращает null, если отсутствуют. Поля объекта:
| Поле | Тип | Описание |
|---|---|---|
dc_title |
string | null |
Заголовок документа |
dc_creator |
string[] | null |
Список создателей |
dc_description |
string | null |
Описание |
xmp_creator_tool |
string | null |
Инструмент создания |
xmp_create_date |
string | null |
Дата создания |
xmp_modify_date |
string | null |
Дата изменения |
pdf_producer |
string | null |
Производитель PDF |
Поля форм
getFormFields() -> Array
Получение всех полей формы с именем, типом, значением и флагами.
| Поле | Тип | Описание |
|---|---|---|
name |
string |
Имя поля |
field_type |
string |
Тип поля (text, checkbox, etc.) |
value |
string |
Текущее значение |
flags |
number |
Флаги поля |
const fields = doc.getFormFields();
for (const f of fields) {
console.log(`${f.name} (${f.field_type}) = ${f.value}`);
}
hasXfa() -> boolean
Проверка, содержит ли документ формы XFA.
getFormFieldValue(name) -> any
Получение значения поля формы по имени. Returns a string, boolean, or null depending on the field type.
| Параметр | Тип | Описание |
|---|---|---|
name |
string |
Имя поля |
setFormFieldValue(name, value) -> void
Установка значения поля формы по имени.
| Параметр | Тип | Описание |
|---|---|---|
name |
string |
Имя поля |
value |
string | boolean |
Новое значение поля |
exportFormData(format?) -> Uint8Array
Экспорт данных формы в FDF (по умолчанию) или XFDF.
| Parameter | Type | Default | Описание |
|---|---|---|---|
format |
string |
"fdf" |
Формат экспорта: "fdf" или "xfdf" |
Редактирование
Метаданные
| Метод | Параметры | Описание |
|---|---|---|
setTitle(title) |
string |
Установить заголовок документа |
setAuthor(author) |
string |
Установить автора документа |
setSubject(subject) |
string |
Установить тему документа |
setKeywords(keywords) |
string |
Установить ключевые слова документа |
Поворот страниц
| Метод | Параметры | Описание |
|---|---|---|
pageRotation(pageIndex) |
number |
Получить текущий поворот (0, 90, 180, 270) |
setPageRotation(pageIndex, degrees) |
number, number |
Установить абсолютный поворот |
rotatePage(pageIndex, degrees) |
number, number |
Добавить к текущему повороту |
rotateAllPages(degrees) |
number |
Повернуть все страницы |
Размеры страниц
| Метод | Параметры | Описание |
|---|---|---|
pageMediaBox(pageIndex) |
number |
Get MediaBox [llx, lly, urx, ury] |
setPageMediaBox(pageIndex, llx, lly, urx, ury) |
number, ... |
Установить MediaBox |
pageCropBox(pageIndex) |
number |
Получить CropBox (может быть null) |
setPageCropBox(pageIndex, llx, lly, urx, ury) |
number, ... |
Установить CropBox |
cropMargins(left, right, top, bottom) |
number, ... |
Обрезать поля всех страниц |
Удаление / замазывание
| Метод | Параметры | Описание |
|---|---|---|
eraseRegion(pageIndex, llx, lly, urx, ury) |
number, ... |
Стереть область |
eraseRegions(pageIndex, rects) |
number, Float32Array |
Стереть несколько областей |
clearEraseRegions(pageIndex) |
number |
Очистить ожидающие стирания |
Аннотации и замазывание
| Метод | Параметры | Описание |
|---|---|---|
flattenPageAnnotations(pageIndex) |
number |
Сведение аннотаций на странице |
flattenAllAnnotations() |
– | Сведение всех аннотаций |
applyPageRedactions(pageIndex) |
number |
Применить замазывание на странице |
applyAllRedactions() |
– | Применить все замазывания |
Сведение форм
| Метод | Параметры | Описание |
|---|---|---|
flattenForms() |
– | Сведение всех полей формы в содержимое страницы |
flattenFormsOnPage(pageIndex) |
number |
Сведение форм на конкретной странице |
Объединение и встраивание
mergeFrom(data) -> number
Объединить страницы из другого PDF. Возвращает количество объединённых страниц.
| Параметр | Тип | Описание |
|---|---|---|
data |
Uint8Array |
Байты исходного PDF-файла |
embedFile(name, data) -> void
Прикрепить файл к PDF.
| Параметр | Тип | Описание |
|---|---|---|
name |
string |
Имя файла вложения |
data |
Uint8Array |
Содержимое файла |
Работа с изображениями
| Метод | Параметры | Описание |
|---|---|---|
repositionImage(pageIndex, name, x, y) |
number, string, number, number |
Переместить изображение |
resizeImage(pageIndex, name, w, h) |
number, string, number, number |
Изменить размер изображения |
setImageBounds(pageIndex, name, x, y, w, h) |
number, string, ... |
Установить границы изображения |
Рендеринг
| Метод | Параметры | Возврат | Описание |
|---|---|---|---|
renderPage(pageIndex, dpi?) |
number, number |
Uint8Array |
Рендеринг страницы в PNG байты |
flattenToImages(dpi?) |
number |
Uint8Array |
Преобразование всех страниц в PDF на основе изображений |
Сохранение
saveToBytes() -> Uint8Array
Сохранить отредактированный PDF в виде байтов.
saveEncryptedToBytes(password, ownerPassword?, allowPrint?, allowCopy?, allowModify?, allowAnnotate?) -> Uint8Array
Сохранить с шифрованием AES-256.
| Parameter | Type | Default | Описание |
|---|---|---|---|
password |
string |
– | Пароль пользователя |
ownerPassword |
string |
user password | Пароль владельца |
allowPrint |
boolean |
true |
Разрешить печать |
allowCopy |
boolean |
true |
Разрешить копирование |
allowModify |
boolean |
false |
Разрешить изменение |
allowAnnotate |
boolean |
true |
Разрешить аннотации |
free()
Освобождение памяти WASM. Всегда вызывайте по завершении работы с документом.
WasmPdf
Фабричный класс для создания новых PDF.
import { WasmPdf } from "pdf-oxide-wasm";
Статические методы
WasmPdf.fromMarkdown(content, title?, author?) -> WasmPdf
Создать PDF из текста Markdown.
| Parameter | Type | Default | Описание |
|---|---|---|---|
content |
string |
– | Содержимое Markdown |
title |
string |
– | Заголовок документа |
author |
string |
– | Автор документа |
WasmPdf.fromHtml(content, title?, author?) -> WasmPdf
Создать PDF из HTML.
WasmPdf.fromText(content, title?, author?) -> WasmPdf
Создать PDF из простого текста.
WasmPdf.fromImageBytes(data) -> WasmPdf
Создать одностраничный PDF из байтов изображения.
| Параметр | Тип | Описание |
|---|---|---|
data |
Uint8Array |
Байты файла изображения (JPEG, PNG) |
WasmPdf.fromMultipleImageBytes(imagesArray) -> WasmPdf
Создать многостраничный PDF из нескольких изображений, одна страница на изображение.
| Параметр | Тип | Описание |
|---|---|---|
imagesArray |
Uint8Array[] |
Массив байтов файлов изображений |
Методы экземпляра
toBytes() -> Uint8Array
Получить PDF в виде байтов.
size -> number
Размер PDF в байтах (свойство только для чтения).
const pdf = WasmPdf.fromMarkdown("# Hello World\n\nThis is a PDF.");
console.log(`PDF size: ${pdf.size} bytes`);
writeFileSync("output.pdf", pdf.toBytes());
Доступность функций
Некоторые функции требуют нативных зависимостей и недоступны в WebAssembly:
| Функция | WASM | Примечания |
|---|---|---|
| Text extraction | Yes | Полная поддержка |
| Structured extraction | Yes | Символы, span’ы |
| PDF creation | Yes | Markdown, HTML, текст, изображения |
| PDF editing | Yes | Метаданные, поворот, размеры, стирание |
| Form fields | Yes | Чтение, запись, экспорт, сведение |
| Search | Yes | Полная поддержка регулярных выражений |
| Encryption | Yes | Чтение и запись AES-256 |
| Annotations | Yes | Чтение, сведение, замазывание |
| Merge PDFs | Yes | Объединить страницы из другого PDF |
| Embedded files | Yes | Прикрепление файлов к PDF |
| Page labels | Yes | Чтение диапазонов меток страниц |
| XMP metadata | Yes | Чтение метаданных XMP |
| OCR | No | Требуется нативный ONNX Runtime |
| Digital signatures | No | Требуются нативные криптографические библиотеки |
| Page rendering | No | Требуется нативный tiny-skia |
| Barcodes | No | Требуется нативный рендеринг |
| Office conversion | No | Требуется нативный LibreOffice |
Обработка ошибок
Все методы, которые могут завершиться с ошибкой, вызывают объекты JavaScript Error:
try {
const doc = new WasmPdfDocument(new Uint8Array([0, 1, 2]));
} catch (e) {
console.error(`Failed to open: ${e.message}`);
}
TypeScript
Полные определения типов включены в пакет:
import { WasmPdfDocument, WasmPdf } from "pdf-oxide-wasm";
const doc: WasmPdfDocument = new WasmPdfDocument(bytes);
const text: string = doc.extractText(0);
const pdf: WasmPdf = WasmPdf.fromMarkdown("# Hello");