Referência da API JavaScript

O PDF Oxide fornece bindings WebAssembly para JavaScript e TypeScript. O pacote npm pdf-oxide-wasm funciona tanto em Node.js quanto em navegadores.

npm install pdf-oxide-wasm

Para a API Rust, veja a Referência da API Rust. Para the Python API, see the Referência da API Python. Para detalhes de tipos, veja Tipos e Enums.

---

WasmPdfDocument

A classe principal para abrir, extrair, editar e salvar PDFs.

import { WasmPdfDocument } from "pdf-oxide-wasm";

Construtor

new WasmPdfDocument(data)

Carregar um documento PDF a partir de bytes brutos.

Parâmetro	Tipo	Descrição
data	Uint8Array	O conteúdo do arquivo PDF

Lança: Error se o PDF for inválido ou não puder ser analisado.

const bytes = new Uint8Array(readFileSync("document.pdf"));
const doc = new WasmPdfDocument(bytes);

---

Somente Leitura

pageCount() -> number

Obter o número de páginas no documento.

version() -> Uint8Array

Obter o Versão do PDF as [major, minor].

const [major, minor] = doc.version();
console.log(`PDF ${major}.${minor}`);

authenticate(password) -> boolean

Descriptografar um PDF criptografado. Retorna true se a autenticação foi bem-sucedida.

Parâmetro	Tipo	Descrição
password	string	A string de senha

hasStructureTree() -> boolean

Verificar se o documento é um PDF Marcado com uma árvore de estrutura.

---

Extração de Texto

extractText(pageIndex) -> string

Extrair texto simples de uma página única.

Parâmetro	Tipo	Descrição
pageIndex	number	Número de página baseado em zero

const text = doc.extractText(0);

extractAllText() -> string

Extrair texto simples de todas as páginas, separado por caracteres de avanço de formulário.

extractChars(pageIndex) -> Array

Extrair caracteres individuais com posicionamento preciso e metadados de fonte.

Parâmetro	Tipo	Descrição
pageIndex	number	Número de página baseado em zero

Retorna: Array de objetos com campos:

Campo	Tipo	Descrição
char	string	O caractere
bbox	{x, y, width, height}	Caixa delimitadora
font_name	string	Nome da fonte
font_size	number	Tamanho da fonte em pontos
font_weight	string	Peso (Normal, Bold, etc.)
is_italic	boolean	Indicador de itálico
color	{r, g, b}	Cor 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

Extrair spans de texto estilizados com metadados de fonte.

Parâmetro	Tipo	Descrição
pageIndex	number	Número de página baseado em zero

Retorna: Array de objetos com campos:

Campo	Tipo	Descrição
text	string	O conteúdo de texto
bbox	{x, y, width, height}	Caixa delimitadora
font_name	string	Nome da fonte
font_size	number	Tamanho da fonte em pontos
font_weight	string	Peso (Normal, Bold, etc.)
is_italic	boolean	Indicador de itálico
color	{r, g, b}	Cor 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}`);
}

---

Conversão de Formato

toMarkdown(pageIndex, detectHeadings?, includeImages?, includeFormFields?) -> string

Converter uma única página para Markdown.

Parâmetro	Tipo	Padrão	Descrição
pageIndex	number	–	Número de página baseado em zero
detectHeadings	boolean	true	Detectar cabeçalhos pelo tamanho da fonte
includeImages	boolean	true	Incluir imagens
includeFormFields	boolean	true	Incluir valores de campos de formulário

toMarkdownAll(detectHeadings?, includeImages?, includeFormFields?) -> string

Converter todas as páginas para Markdown.

toHtml(pageIndex, preserveLayout?, detectHeadings?, includeFormFields?) -> string

Converter uma única página para HTML.

Parâmetro	Tipo	Padrão	Descrição
pageIndex	number	–	Número de página baseado em zero
preserveLayout	boolean	false	Preservar layout visual
detectHeadings	boolean	true	Detectar cabeçalhos
includeFormFields	boolean	true	Incluir valores de campos de formulário

toHtmlAll(preserveLayout?, detectHeadings?, includeFormFields?) -> string

Converter todas as páginas para HTML.

toPlainText(pageIndex) -> string

Converter uma única página para texto simples.

toPlainTextAll() -> string

Converter todas as páginas para texto simples.

---

Busca

search(pattern, caseInsensitive?, literal?, wholeWord?, maxResults?) -> Array

Buscar texto em todas as páginas.

Parâmetro	Tipo	Padrão	Descrição
pattern	string	–	Padrão de busca (string ou regex)
caseInsensitive	boolean	false	Busca insensível a maiúsculas/minúsculas
literal	boolean	false	Tratar padrão como string literal
wholeWord	boolean	false	Corresponder apenas palavras inteiras
maxResults	number	–	Máximo de resultados a retornar

Retorna: Array de objetos com campos:

Campo	Tipo	Descrição
page	number	Número da página
text	string	Texto correspondente
bbox	object	Caixa delimitadora
start_index	number	Índice inicial no texto da página
end_index	number	Índice final no texto da página

searchPage(pageIndex, pattern, caseInsensitive?, literal?, wholeWord?, maxResults?) -> Array

Buscar texto dentro de uma página única.

---

Informações de Imagem

extractImages(pageIndex) -> Array

Obter metadados de imagem para uma página.

Campo	Tipo	Descrição
width	number	Largura da imagem em pixels
height	number	Altura da imagem em pixels
color_space	string	Espaço de cor (ex.: DeviceRGB)
bits_per_component	number	Bits por canal de cor
bbox	object	Posição na página

extractImageBytes(pageIndex) -> Array

Extrair bytes brutos de imagem de uma página. Retorna um array de objetos:

Campo	Tipo	Descrição
width	number	Largura da imagem em pixels
height	number	Altura da imagem em pixels
data	Uint8Array	Bytes brutos da imagem
format	string	Formato da imagem

pageImages(pageIndex) -> Array

Obter nomes de imagens e limites para operações de posicionamento.

Campo	Tipo	Descrição
name	string	Nome do XObject
bounds	number[]	[x, y, width, height]
matrix	number[]	Matriz de transformação [a, b, c, d, e, f]

---

Estrutura do Documento

getOutline() -> Array | null

Obter marcadores / índice do documento. Retorna null se nenhum índice existir.

getAnnotations(pageIndex) -> Array

Obter metadados de anotação (tipo, retângulo, conteúdo, etc.) para uma página.

extractPaths(pageIndex) -> Array

Obter caminhos vetoriais (linhas, curvas, formas) de uma página.

pageLabels() -> Array

Obter intervalos de rótulos de página. Retorna um array de objetos:

Campo	Tipo	Descrição
start_page	number	Primeira página neste intervalo
style	string	Estilo de numeração
prefix	string	Prefixo do rótulo
start_value	number	Número inicial

xmpMetadata() -> object | null

Obter metadados XMP. Retorna null se não presente. Os campos do objeto incluem:

Campo	Tipo	Descrição
dc_title	string | null	Título do documento
dc_creator	string[] | null	Lista de criadores
dc_description	string | null	Descrição
xmp_creator_tool	string | null	Ferramenta criadora
xmp_create_date	string | null	Data de criação
xmp_modify_date	string | null	Data de modificação
pdf_producer	string | null	Produtor PDF

---

Campos de Formulário

getFormFields() -> Array

Obter todos os campos de formulário com nome, tipo, valor e sinalizadores.

Campo	Tipo	Descrição
name	string	Nome do campo
field_type	string	Tipo de campo (texto, caixa de seleção, etc.)
value	string	Valor atual
flags	number	Sinalizadores do campo

const fields = doc.getFormFields();
for (const f of fields) {
  console.log(`${f.name} (${f.field_type}) = ${f.value}`);
}

hasXfa() -> boolean

Verificar se o documento contém formulários XFA.

getFormFieldValue(name) -> any

Obter um valor de campo de formulário por nome. Retorna uma string, boolean ou null dependendo do tipo do campo.

Parâmetro	Tipo	Descrição
name	string	Nome do campo

setFormFieldValue(name, value) -> void

Definir um valor de campo de formulário por nome.

Parâmetro	Tipo	Descrição
name	string	Nome do campo
value	string | boolean	New field value

exportFormData(format?) -> Uint8Array

Exportar dados de formulário como FDF (padrão) ou XFDF.

Parâmetro	Tipo	Padrão	Descrição
format	string	"fdf"	Formato de exportação: "fdf" ou "xfdf"

---

Edição

Metadados

Método	Parâmetros	Descrição
setTitle(title)	string	Definir título do documento
setAuthor(author)	string	Definir autor do documento
setSubject(subject)	string	Definir assunto do documento
setKeywords(keywords)	string	Definir palavras-chave do documento

Rotacao de Páginas

Método	Parâmetros	Descrição
pageRotation(pageIndex)	number	Obter rotação atual (0, 90, 180, 270)
setPageRotation(pageIndex, degrees)	number, number	Definir rotação absoluta
rotatePage(pageIndex, degrees)	number, number	Adicionar à rotação atual
rotateAllPages(degrees)	number	Rotacionar todas as páginas

Dimensões da Página

Método	Parâmetros	Descrição
pageMediaBox(pageIndex)	number	Obter MediaBox [llx, lly, urx, ury]
setPageMediaBox(pageIndex, llx, lly, urx, ury)	number, ...	Definir MediaBox
pageCropBox(pageIndex)	number	Obter CropBox (pode ser null)
setPageCropBox(pageIndex, llx, lly, urx, ury)	number, ...	Definir CropBox
cropMargins(left, right, top, bottom)	number, ...	Recortar todas as margens da página

Apagar / Branquear

Método	Parâmetros	Descrição
eraseRegion(pageIndex, llx, lly, urx, ury)	number, ...	Apagar uma região
eraseRegions(pageIndex, rects)	number, Float32Array	Apagar múltiplas regiões
clearEraseRegions(pageIndex)	number	Limpar apagamentos pendentes

Anotações e Redação

Método	Parâmetros	Descrição
flattenPageAnnotations(pageIndex)	number	Achatar anotações na página
flattenAllAnnotations()	–	Achatar todas as anotações
applyPageRedactions(pageIndex)	number	Aplicar redações na página
applyAllRedactions()	–	Aplicar todas as redações

Achatamento de Formulários

Método	Parâmetros	Descrição
flattenForms()	–	Achatar todos os campos de formulário no conteúdo da página
flattenFormsOnPage(pageIndex)	number	Achatar formulários em uma página específica

Mesclar e Incorporar

mergeFrom(data) -> number

Mesclar páginas de outro PDF. Retorna o número de páginas mescladas.

Parâmetro	Tipo	Descrição
data	Uint8Array	Os bytes do arquivo PDF de origem

embedFile(name, data) -> void

Anexar um arquivo ao PDF.

Parâmetro	Tipo	Descrição
name	string	Nome do arquivo para o anexo
data	Uint8Array	Conteúdo do arquivo

Manipulacao de Imagens

Método	Parâmetros	Descrição
repositionImage(pageIndex, name, x, y)	number, string, number, number	Mover imagem
resizeImage(pageIndex, name, w, h)	number, string, number, number	Redimensionar imagem
setImageBounds(pageIndex, name, x, y, w, h)	number, string, ...	Definir limites da imagem

Renderização

Método	Parâmetros	Retorno	Descrição
renderPage(pageIndex, dpi?)	number, number	Uint8Array	Renderizar página em bytes PNG
flattenToImages(dpi?)	number	Uint8Array	Achatar todas as páginas em PDF baseado em imagens

---

Salvar

saveToBytes() -> Uint8Array

Salvar o PDF editado como bytes.

saveEncryptedToBytes(password, ownerPassword?, allowPrint?, allowCopy?, allowModify?, allowAnnotate?) -> Uint8Array

Salvar com criptografia AES-256.

Parâmetro	Tipo	Padrão	Descrição
password	string	–	Senha de usuário
ownerPassword	string	user password	Senha do proprietário
allowPrint	boolean	true	Permitir impressão
allowCopy	boolean	true	Permitir cópia
allowModify	boolean	false	Permitir modificação
allowAnnotate	boolean	true	Permitir anotações

free()

Liberar memória WASM. Sempre chame isto quando terminar com o documento.

---

WasmPdf

Classe fábrica para criar novos PDFs.

import { WasmPdf } from "pdf-oxide-wasm";

Métodos Estáticos

WasmPdf.fromMarkdown(content, title?, author?) -> WasmPdf

Criar um PDF a partir de texto Markdown.

Parâmetro	Tipo	Padrão	Descrição
content	string	–	Conteúdo Markdown
title	string	–	Título do documento
author	string	–	Autor do documento

WasmPdf.fromHtml(content, title?, author?) -> WasmPdf

Criar um PDF a partir de HTML.

WasmPdf.fromText(content, title?, author?) -> WasmPdf

Criar um PDF a partir de texto simples.

WasmPdf.fromImageBytes(data) -> WasmPdf

Criar um PDF de uma única página a partir de bytes de imagem.

Parâmetro	Tipo	Descrição
data	Uint8Array	Bytes do arquivo de imagem (JPEG, PNG)

WasmPdf.fromMultipleImageBytes(imagesArray) -> WasmPdf

Criar um PDF de múltiplas páginas a partir de múltiplas imagens, uma página por imagem.

Parâmetro	Tipo	Descrição
imagesArray	Uint8Array[]	Array de bytes de arquivo de imagem

Métodos de Instância

toBytes() -> Uint8Array

Obter o PDF como bytes.

size -> number

Tamanho do PDF em bytes (propriedade somente leitura).

const pdf = WasmPdf.fromMarkdown("# Hello World\n\nThis is a PDF.");
console.log(`PDF size: ${pdf.size} bytes`);
writeFileSync("output.pdf", pdf.toBytes());

---

Disponibilidade de Funcionalidades

Algumas funcionalidades requerem dependências nativas e não estão disponíveis em WebAssembly:

Funcionalidade	WASM	Notas
Extração de texto	Sim	Suporte completo
Extração estruturada	Sim	Caracteres, spans
Criação de PDF	Sim	Markdown, HTML, texto, imagens
Edição de PDF	Sim	Metadados, rotação, dimensões, apagar
Campos de formulário	Sim	Ler, escrever, exportar, achatar
Search	Sim	Suporte completo a regex
Criptografia	Sim	Leitura e escrita AES-256
Annotations	Sim	Ler, achatar, redigir
Mesclar PDFs	Sim	Mesclar páginas de outro PDF
Arquivos incorporados	Sim	Anexar arquivos a PDFs
Page labels	Sim	Ler intervalos de rótulos de página
XMP metadata	Sim	Ler metadados XMP
OCR	No	Requer ONNX Runtime nativo
Assinaturas digitais	No	Requer bibliotecas criptográficas nativas
Renderização de página	No	Requer tiny-skia nativo
Barcodes	No	Requer renderização nativa
Conversão Office	No	Requer LibreOffice nativo

---

Tratamento de Erros

Todos os métodos que podem falhar lançam objetos JavaScript Error:

try {
  const doc = new WasmPdfDocument(new Uint8Array([0, 1, 2]));
} catch (e) {
  console.error(`Failed to open: ${e.message}`);
}

---

TypeScript

Definições de tipo completas estão incluídas no pacote:

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");