JavaScript API 参考

PDF Oxide 为 JavaScript 和 TypeScript 提供 WebAssembly 绑定。npm 包 pdf-oxide-wasm 同时支持 Node.js 和浏览器。

npm install pdf-oxide-wasm

关于 Rust API，请参见 Rust API 参考. 关于 Python API，请参见 Python API 参考. 关于类型详情，请参见 类型与枚举.

---

WasmPdfDocument

用于打开、提取、编辑和保存 PDF 的主要类.

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

构造函数

new WasmPdfDocument(data)

从原始字节加载 PDF 文档。

参数	类型	描述
data	Uint8Array	PDF 文件内容

抛出： Error if the PDF is invalid or cannot be parsed.

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	密码字符串

has结构Tree() -> boolean

检查文档是否为带有结构树的 Tagged PDF。

---

文本提取

extractText(pageIndex) -> string

从单个页面提取纯文本。

参数	类型	描述
pageIndex	number	从零开始的页码

const text = doc.extractText(0);

extractAllText() -> string

从所有页面提取纯文本，以换页符分隔。

extractChars(pageIndex) -> Array

提取逐字符精确位置和字体元数据。

参数	类型	描述
pageIndex	number	从零开始的页码

返回值： Array of objects with fields:

字段	类型	描述
char	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 color (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

提取带字体元数据的样式文本段。

参数	类型	描述
pageIndex	number	从零开始的页码

返回值： Array of objects with fields:

字段	类型	描述
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 color (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。

参数	类型	默认值	描述
pageIndex	number	–	从零开始的页码
detectHeadings	boolean	true	根据字体大小检测标题
includeImages	boolean	true	包含图片
includeFormFields	boolean	true	包含表单字段值

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

将所有页面转换为 Markdown。

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

将单个页面转换为 HTML。

参数	类型	默认值	描述
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

在所有页面上搜索文本。

参数	类型	默认值	描述
pattern	string	–	搜索模式（字符串或正则表达式）
caseInsensitive	boolean	false	大小写不敏感搜索
literal	boolean	false	将模式视为字面字符串
wholeWord	boolean	false	仅匹配完整单词
maxResults	number	–	返回的最大结果数

返回值： Array of objects with fields:

字段	类型	描述
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	Color space (e.g. 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

获取所有表单字段。with name, type, value, and flags.

字段	类型	描述
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

按名称获取表单字段值。根据字段类型返回 string、boolean 或 null。

参数	类型	描述
name	string	字段名称

setFormFieldValue(name, value) -> void

按名称设置表单字段值。

参数	类型	描述
name	string	字段名称
value	string | boolean	新字段值

exportFormData(format?) -> Uint8Array

导出表单数据为 FDF（默认）或 XFDF 格式。

参数	类型	默认值	描述
format	string	"fdf"	导出格式： "fdf" or "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 加密保存。

参数	类型	默认值	描述
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

从 Markdown 文本创建 PDF。

参数	类型	默认值	描述
content	string	–	Markdown 内容
title	string	–	文档标题
author	string	–	文档作者

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

从 HTML 创建 PDF。

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	说明
文本提取	Yes	完全支持
结构化提取	Yes	字符、文本段
PDF 创建	Yes	Markdown、HTML、文本、图片
PDF 编辑	Yes	元数据、旋转、尺寸、擦除
表单字段	Yes	读取、写入、导出、扁平化
Search	Yes	完全正则支持
加密	Yes	AES-256 读写
Annotations	Yes	读取、扁平化、涂黑
合并 PDF	Yes	从另一个 PDF 合并页面
嵌入文件	Yes	将文件附加到 PDF
Page labels	Yes	读取页面标签范围
XMP metadata	Yes	读取 XMP 元数据
OCR	No	需要原生 ONNX 运行时
数字签名	No	需要原生加密库
页面渲染	No	需要原生 tiny-skia
Barcodes	No	需要原生渲染
Office 转换	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");