JavaScript API 参考

PDF Oxide 为 JavaScript 和 TypeScript 提供 WebAssembly 绑定。npm 包 pdf-oxide-wasm 可在 Node.js、浏览器、打包工具、Deno 以及 Cloudflare Workers 中运行。

npm install pdf-oxide-wasm

多目标打包 (v0.3.38)

pdf-oxide-wasm 现在通过 package.json 的条件导出 (conditional exports) 并列提供三套构建。选用与你的运行时匹配的子路径即可——在大多数环境下，自动路由的顶层 import 也会经由 exports 字段正确解析。

子路径	目标环境
pdf-oxide-wasm/nodejs	Node.js (CommonJS + ESM)
pdf-oxide-wasm/bundler	Vite、webpack、Rollup、esbuild、Bun
pdf-oxide-wasm/web	浏览器、Deno、Cloudflare Workers

// Node.js
import { WasmPdfDocument } from "pdf-oxide-wasm/nodejs";

// Vite / webpack / Rollup
import init, { WasmPdfDocument } from "pdf-oxide-wasm/bundler";
await init();

// Browsers / Deno / Workers
import init, { WasmPdfDocument } from "pdf-oxide-wasm/web";
await init();

这修复了 v0.3.38 之前在浏览器打包工具下抛出的 ReferenceError: Can't find variable: __dirname 错误。

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

部分方法受 Rust 构建特性（rendering、signatures、barcodes、ocr-tract）控制。默认的 pdf-oxide-wasm 包启用了常用特性集；OCR 则随独立的 wasm-ocr 构建一起发布。参见 功能可用性。

---

模块函数

在包顶层导出的自由函数。

import {
  setLogLevel, disableLogging,
  generateBarcodeSvg, generateQrSvg,
  planSplitByBookmarks, splitByBookmarks,
  setCryptoPolicy, cryptoPolicy, cryptoInventory, cryptoCbom,
  modelManifest, prefetchAvailable,
  signPdfBytes, signPdfBytesPades, hasDocumentTimestamp,
} from "pdf-oxide-wasm";

日志

setLogLevel(level)   // Set log verbosity: "off" | "error" | "warn" | "info" | "debug" | "trace"
disableLogging()     // Silence all log output

条形码

generateBarcodeSvg(barcodeType, data) -> string  // 1D barcode as SVG; type 0–7 (Code128, Code39, Ean13, Ean8, UpcA, Itf, Code93, Codabar)
generateQrSvg(data, errorCorrection, size) -> string  // QR code as SVG; errorCorrection 0=Low 1=Medium 2=Quartile 3=High

按书签拆分

planSplitByBookmarks(srcBytes, titlePrefix, ignoreCase, level, includeFrontMatter) -> Array  // Plan a split without producing PDFs; returns segment descriptors
splitByBookmarks(srcBytes, titlePrefix, ignoreCase, level, includeFrontMatter) -> Array       // Split at bookmark boundaries; returns [segment, bytes] pairs (level 0=all depths, 1=top-level)

加密治理

setCryptoPolicy(spec)   // Install the process-wide crypto policy ("compat" | "strict" | "fips-strict"[;…]); fail-closed
cryptoPolicy() -> string  // The active crypto policy as its canonical grammar string
cryptoInventory() -> string[]  // Algorithm tokens exercised so far this process
cryptoCbom() -> string  // CycloneDX 1.6 Cryptographic Bill of Materials (JSON string)

OCR 模型供给

modelManifest() -> string   // JSON manifest of OCR detector/recognizer cache filenames and source URLs (host-side fetch)
prefetchAvailable() -> boolean  // Whether this build can download OCR models to a local cache (always false in WASM)

签名（自由函数）

signPdfBytes(pdfData, cert, reason?, location?) -> Uint8Array  // Sign raw PDF bytes with a WasmCertificate; returns the signed PDF
signPdfBytesPades(pdfData, cert, level, timestampToken?, revocation?, reason?, location?) -> Uint8Array  // Sign at a PAdES baseline level (BB/BT/BLt); pass a pre-fetched RFC 3161 token for BT/BLt
hasDocumentTimestamp(pdfData) -> boolean  // Whether the PDF carries a document-scoped /DocTimeStamp (PAdES-B-LTA)

---

WasmPdfDocument

用于打开、提取、编辑和保存 PDF 的核心类。

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

构造函数

new WasmPdfDocument(data, password?)

从原始字节加载 PDF 文档。

参数	类型	描述
data	Uint8Array	PDF 文件内容
password	string | undefined	加密 PDF 的可选密码

抛出： 当 PDF 无效或无法解析时抛出 Error。

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

静态构造函数

WasmPdfDocument.openFromDocxBytes(data) -> WasmPdfDocument  // Convert DOCX bytes to a PDF document
WasmPdfDocument.openFromPptxBytes(data) -> WasmPdfDocument  // Convert PPTX bytes to a PDF document
WasmPdfDocument.openFromXlsxBytes(data) -> WasmPdfDocument  // Convert XLSX bytes to a PDF document

---

核心只读方法

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 (Tagged PDF)。

签名检查

signatureCount() -> number          // Number of digital signatures in the document
signatures() -> WasmSignature[]     // Parsed signatures (signer, reason, time, verify())
dss() -> Dss | null                 // Document Security Store (certs/CRLs/OCSP), or null

---

文本提取

extractText(pageIndex, region?) -> string

从单页提取纯文本。可传入可选的 [x, y, w, h] 区域以限制提取范围。

参数	类型	描述
pageIndex	number	从零开始的页码
region	number[] | undefined	可选的 [x, y, width, height] 裁剪框

const text = doc.extractText(0);

extractAllText() -> string

提取所有页的纯文本，各页之间以换页符 (form feed) 分隔。

extractStructured(pageIndex) -> string

提取页面的结构化 JSON 表示（块、行、样式）。

extractChars(pageIndex, region?) -> Array

提取单个字符，附带精确定位和字体元数据。

参数	类型	描述
pageIndex	number	从零开始的页码
region	number[] | undefined	可选的 [x, y, width, height] 裁剪框

返回值： 对象数组，包含以下字段：

字段	类型	描述
char	string	字符
bbox	{x, y, width, height}	边界框
fontName	string	字体名称
fontSize	number	字号（磅）
fontWeight	string	字重（Normal、Bold 等）
isItalic	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})`);
}

extractPageText(pageIndex, readingOrder?) -> object

通过一次提取即可获取 span、字符和页面尺寸。比分别调用 extractSpans() + extractChars() 更高效。对多栏 PDF 可传入 "column_aware"。

参数	类型	描述
pageIndex	number	从零开始的页码
readingOrder	string | undefined	"column_aware" 或 "top_to_bottom"（默认）

返回值： 包含以下字段的对象：

字段	类型	描述
spans	Array	span 对象数组
chars	Array	字符对象数组
pageWidth	number	页面宽度（PDF 磅）
pageHeight	number	页面高度（PDF 磅）
text	string	完整文本内容

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}`);
}

extractSpans(pageIndex, region?, readingOrder?) -> Array

提取带字体元数据的样式化文本段 (span)。对多栏 PDF，可将 readingOrder 传为 "column_aware"。

参数	类型	描述
pageIndex	number	从零开始的页码
region	number[] | undefined	可选的 [x, y, width, height] 裁剪框
readingOrder	string | undefined	"column_aware" 或 "top_to_bottom"（默认）

返回值： 对象数组，包含以下字段：

字段	类型	描述
text	string	文本内容
bbox	{x, y, width, height}	边界框
fontName	string	字体名称
fontSize	number	字号（磅）
fontWeight	string	字重（Normal、Bold 等）
isItalic	boolean	斜体标志
isMonospace	boolean	字体是否等宽
charWidths	number[]	每个字形的步进宽度
color	{r, g, b}	RGB 颜色 (0.0–1.0)

const spans = doc.extractSpans(0);
for (const span of spans) {
  console.log(`"${span.text}" size=${span.fontSize}`);
}

单词、行、表格

extractWords(pageIndex, region?) -> Array       // Word-level boxes with text + font metadata
extractTextLines(pageIndex, region?) -> Array   // Line-level boxes, each with its words
extractTables(pageIndex, region?) -> Array      // Detected tables with rows/cells (text + bboxes)

---

页眉 / 页脚制品 (Artifacts)

检测并移除或擦除重复出现的页眉、页脚以及页面装饰类制品。

removeHeaders(threshold) -> number     // Remove detected headers across the document; returns count removed
removeFooters(threshold) -> number     // Remove detected footers; returns count removed
removeArtifacts(threshold) -> number   // Remove detected page artifacts; returns count removed
eraseHeader(pageIndex)                 // Queue an erase of the header region on a page
editHeader(pageIndex)                  // Mark the header region for editing on a page
eraseFooter(pageIndex)                 // Queue an erase of the footer region on a page
editFooter(pageIndex)                  // Mark the footer region for editing on a page
eraseArtifacts(pageIndex)              // Queue an erase of detected artifacts on a page

---

区域提取

within(pageIndex, region) -> WasmPdfPageRegion

将后续提取范围限定到页面的某个矩形区域。region 为 [x, y, width, height]。参见 WasmPdfPageRegion。

const region = doc.within(0, [50, 600, 400, 150]);
const text = region.extractText();

---

格式转换

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

将所有页转换为纯文本。

Office 往返转换

toDocxBytes() -> Uint8Array   // Export the document as a DOCX file
toPptxBytes() -> Uint8Array   // Export the document as a PPTX file
toXlsxBytes() -> Uint8Array   // Export the document as an XLSX file

---

搜索

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

跨所有页搜索文本。

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

返回值： 对象数组，包含以下字段：

字段	类型	描述
page	number	页码
text	string	匹配到的文本
bbox	object	边界框
startIndex	number	在页面文本中的起始索引
endIndex	number	在页面文本中的结束索引

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

在单页内搜索文本。

---

图像信息

extractImages(pageIndex) -> Array

获取某页的图像元数据。

字段	类型	描述
width	number	图像宽度（像素）
height	number	图像高度（像素）
colorSpace	string	色彩空间（如 DeviceRGB）
bitsPerComponent	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]

---

矢量内容

extractPaths(pageIndex, region?) -> Array   // Vector paths (lines, curves, shapes) on a page
extractRects(pageIndex, region?) -> Array   // Axis-aligned rectangles detected from path segments
extractLines(pageIndex, region?) -> Array   // Straight line segments detected from path data

---

文档结构

getOutline() -> Array | null

获取文档书签 / 目录。若不存在大纲则返回 null。

getAnnotations(pageIndex) -> Array

获取某页的注释元数据（类型、矩形、内容等）。

pageLabels() -> Array

获取页面标签范围。返回对象数组：

字段	类型	描述
startPage	number	该范围的首页
style	string	编号样式
prefix	string	标签前缀
startValue	number	起始编号

xmpMetadata() -> object | null

获取 XMP 元数据。若不存在则返回 null。对象字段包括：

字段	类型	描述
dcTitle	string | null	文档标题
dcCreator	string[] | null	创建者列表
dcDescription	string | null	描述
xmpCreatorTool	string | null	创建工具
xmpCreateDate	string | null	创建日期
xmpModifyDate	string | null	修改日期
pdfProducer	string | null	PDF 生成器

---

表单字段

getFormFields() -> Array

获取所有表单字段，包含名称、类型、值和标志位。

字段	类型	描述
name	string	字段名称
fieldType	string	字段类型（text、checkbox 等）
value	string	当前值
flags	number	字段标志位

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

hasXfa() -> boolean

检查文档是否包含 XFA 表单。

getFormFieldValue(name) -> any

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

setFormFieldValue(name, value) -> void

按名称设置表单字段值。

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

exportFormData(format?) -> Uint8Array

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

参数	类型	默认值	描述
format	string	"fdf"	导出格式："fdf" 或 "xfdf"

表单扁平化

flattenForms()                    // Flatten all form fields into page content
flattenFormsOnPage(pageIndex)     // Flatten forms on a specific page
flattenWarnings() -> string[]     // Warnings produced by the last flatten operation

---

编辑

元数据

方法	参数	描述
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	获取 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, ...	裁剪所有页面的边距

页面操作

deletePage(index)                 // Delete a page by index
movePage(fromIndex, toIndex)      // Move a page to a new position
extractPages(pages) -> Uint8Array // Build a new PDF from the given page indices

擦除 / 涂白

方法	参数	描述
eraseRegion(pageIndex, llx, lly, urx, ury)	number, ...	擦除一个区域
eraseRegions(pageIndex, rects)	number, Float32Array	擦除多个区域
clearEraseRegions(pageIndex)	number	清除待处理的擦除

注释与涂黑 (Redaction)

方法	参数	描述
flattenPageAnnotations(pageIndex)	number	扁平化某页上的注释
flattenAllAnnotations()	–	扁平化所有注释
applyPageRedactions(pageIndex)	number	应用某页的涂黑
applyAllRedactions()	–	应用所有涂黑
addRedaction(page, x0, y0, x1, y1, fill?)	number, ...	排入一个涂黑框（可选 [r,g,b] 填充色）
redactionCount(page)	number	统计某页排入的涂黑数量
applyRedactionsDestructive(scrubMetadata?)	boolean	破坏性地移除内容；返回涂黑报告
sanitizeDocument(scrubMetadata?, removeJavascript?, removeEmbeddedFiles?)	boolean, ...	剥离元数据、脚本、嵌入文件；返回报告

合并与嵌入

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, ...	设置图像边界

---

分类与自动提取

classifyDocument() -> string                 // Classify the whole document (e.g. born-digital vs scanned)
classifyPage(pageIndex) -> string            // Classify a single page
extractTextAuto(pageIndex) -> string         // Auto-pick native vs OCR extraction for a page
extractPageAuto(pageIndex, optionsJson?) -> string  // Auto-extraction returning a structured JSON page

---

校验

validatePdfA(level) -> object        // Validate against a PDF/A conformance level (e.g. "2b")
convertToPdfA(level) -> object       // Convert toward a PDF/A level; returns a report
validatePdfUa(level?) -> object      // Validate against PDF/UA accessibility
validatePdfX(level?) -> object       // Validate against a PDF/X print level

---

渲染

需要 rendering 特性。

方法	参数	返回值	描述
renderPage(pageIndex, dpi?)	number, number	Uint8Array	将页面渲染为 PNG 字节（默认 150 dpi）
flattenToImages(dpi?)	number	Uint8Array	将所有页扁平化为基于图像的 PDF

---

OCR

需要 wasm-ocr 构建。参见 WasmOcrEngine。

extractTextOcr(pageIndex, engine) -> string

使用宿主构建的 WasmOcrEngine 在某页上运行 WASM 内置的 OCR 流水线。按阅读顺序返回识别出的文本。

const text = doc.extractTextOcr(0, engine);

---

保存

save() -> Uint8Array

将编辑后的 PDF 保存为字节。saveToBytes() 可作为其别名使用。

saveWithOptions(compress?, garbageCollect?, linearize?) -> Uint8Array

使用显式序列化选项保存。

参数	类型	默认值	描述
compress	boolean	true	压缩对象流
garbageCollect	boolean	true	丢弃未引用的对象
linearize	boolean	false	生成线性化（“快速 Web 查看”）PDF

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

使用 AES-256 加密保存。

参数	类型	默认值	描述
password	string	–	用户密码
ownerPassword	string	用户密码	所有者密码
allowPrint	boolean	true	允许打印
allowCopy	boolean	true	允许复制
allowModify	boolean	true	允许修改
allowAnnotate	boolean	true	允许添加注释

free()

释放 WASM 内存。文档使用完毕后务必调用此方法。

---

WasmPdfPageRegion

由 WasmPdfDocument.within(pageIndex, region) 返回的区域句柄。其提取方法的作用范围被限定在该矩形内。

extractText() -> string       // Plain text within the region
extractChars() -> Array       // Characters within the region
extractWords() -> Array       // Words within the region
extractTextLines() -> Array   // Text lines within the region
extractTables() -> Array      // Tables within the region
extractImages() -> Array      // Images within the region
extractPaths() -> Array       // Vector paths within the region
extractRects() -> Array       // Rectangles within the region
extractLines() -> Array       // Line segments within the region
extractTextOcr(engine?) -> string  // OCR text within the region (wasm-ocr build)

---

WasmPdf

用于创建新 PDF 的工厂类。

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

静态方法

WasmPdf.fromMarkdown(content, title?, author?) -> WasmPdf  // Create a PDF from Markdown text
WasmPdf.fromHtml(content, title?, author?) -> WasmPdf      // Create a PDF from HTML
WasmPdf.fromText(content, title?, author?) -> WasmPdf      // Create a PDF from plain text
WasmPdf.fromBytes(data) -> WasmPdf                         // Open an existing PDF from bytes for modification
WasmPdf.fromImageBytes(data) -> WasmPdf                    // Single-page PDF from one image (JPEG/PNG)
WasmPdf.fromMultipleImageBytes(imagesArray) -> WasmPdf     // Multi-page PDF, one page per image
WasmPdf.merge(pdfs) -> WasmPdf                             // Merge an array of PDF byte buffers into one
WasmPdf.fromHtmlCss(html, css, fontBytes) -> WasmPdf       // HTML + CSS with a single embedded font
WasmPdf.fromHtmlCssWithFonts(html, css, fonts) -> WasmPdf  // HTML + CSS with multiple [name, bytes] fonts

参数	类型	描述
content	string	源内容（Markdown / HTML / 文本）
title	string | undefined	文档标题
author	string | undefined	文档作者
data	Uint8Array	PDF 或图像文件字节
imagesArray	Uint8Array[]	图像文件字节数组
pdfs	Uint8Array[]	待合并的 PDF 文件字节数组

实例方法

toBytes() -> Uint8Array

获取 PDF 字节。

size -> number

PDF 大小（字节）（只读 getter）。

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

---

WasmDocumentBuilder

逐页组合 PDF 的流式、底层页面排版构建器。与 WasmFluentPageBuilder 搭配使用。

import { WasmDocumentBuilder } from "pdf-oxide-wasm";
const builder = new WasmDocumentBuilder();

文档设置

new WasmDocumentBuilder()          // Create an empty builder
title(title)                       // Set document title
author(author)                     // Set document author
subject(subject)                   // Set document subject
keywords(keywords)                 // Set document keywords
creator(creator)                   // Set the creator tool name
onOpen(script)                     // Set a document-level open JavaScript action
taggedPdfUa1()                     // Enable Tagged PDF / PDF/UA-1 output
language(lang)                     // Set the document language (e.g. "en-US")
roleMap(custom, standard)          // Map a custom structure tag to a standard role
registerEmbeddedFont(name, font)   // Register a WasmEmbeddedFont under a name

页面创建与输出

a4Page() -> WasmFluentPageBuilder         // Start a new A4 page
letterPage() -> WasmFluentPageBuilder     // Start a new US Letter page
page(width, height) -> WasmFluentPageBuilder  // Start a custom-size page (points)
commitPage(page)                          // Commit a completed page builder
build() -> Uint8Array                     // Finish and return the PDF bytes
toBytesEncrypted(userPassword, ownerPassword?) -> Uint8Array  // Finish with AES-256 encryption

---

WasmFluentPageBuilder

由 a4Page() / letterPage() / page() 返回的单页构建器。先排入操作，再用 done(builder)（或 builder.commitPage(page)）提交。

文本与排版流

font(name, size)                 // Set the current font and size
at(x, y)                         // Move the cursor to an absolute position
text(text)                       // Draw text at the cursor
heading(level, text)             // Draw a heading (level 1–6)
paragraph(text)                  // Draw a wrapped paragraph
space(points)                    // Advance the cursor vertically
horizontalRule()                 // Draw a horizontal rule
newline()                        // Advance to the next line
columns(columnCount, gapPt, text)  // Lay text out in N balanced columns
footnote(refMark, noteText)      // Add a footnote marker + bottom-of-page note

内联文本块

inline(text)                     // Append an inline text run
inlineBold(text)                 // Append a bold inline run
inlineItalic(text)               // Append an italic inline run
inlineColor(r, g, b, text)       // Append a colored inline run (RGB 0.0–1.0)

链接与表单动作

linkUrl(url)                     // Wrap the last element in a URL link
linkPage(page)                   // Link to another page index
linkNamed(destination)           // Link to a named destination
linkJavascript(script)           // Attach a JavaScript link action
onOpen(script)                   // Page open action
onClose(script)                  // Page close action
fieldKeystroke(script)           // Keystroke JavaScript for the last field
fieldFormat(script)              // Format JavaScript for the last field
fieldValidate(script)            // Validate JavaScript for the last field
fieldCalculate(script)           // Calculate JavaScript for the last field

标记类注释

highlight(r, g, b)               // Highlight the last text run (RGB 0.0–1.0)
underline(r, g, b)               // Underline the last text run
strikeout(r, g, b)               // Strike out the last text run
squiggly(r, g, b)                // Squiggly-underline the last text run
stickyNote(text)                 // Add a sticky note at the cursor
stickyNoteAt(x, y, text)         // Add a sticky note at an absolute position
stamp(name)                      // Add a rubber-stamp annotation (e.g. "Approved")
freeText(x, y, w, h, text)       // Add a free-text annotation box
watermark(text)                  // Add a text watermark
watermarkConfidential()          // Add a "CONFIDENTIAL" watermark
watermarkDraft()                 // Add a "DRAFT" watermark

AcroForm 控件

textField(name, x, y, w, h, defaultValue?)            // Add a text field
checkbox(name, x, y, w, h, checked)                   // Add a checkbox
comboBox(name, x, y, w, h, options, selected?)        // Add a dropdown combo box
radioGroup(name, values, xs, ys, ws, hs, selected?)   // Add a radio-button group (parallel arrays)
pushButton(name, x, y, w, h, caption)                 // Add a clickable push button
signatureField(name, x, y, w, h)                      // Add an unsigned signature placeholder

条形码与图像

barcode1d(barcodeType, data, x, y, w, h)   // Draw a 1D barcode (type 0–7)
barcodeQr(data, x, y, size)                // Draw a QR code
imageWithAlt(bytes, x, y, w, h, altText)   // Embed an image with accessibility alt text
imageArtifact(bytes, x, y, w, h)           // Embed a decorative image as an /Artifact

图形基本元素

rect(x, y, w, h)                                  // Stroked 1pt rectangle outline
filledRect(x, y, w, h, r, g, b)                   // Filled rectangle (RGB 0.0–1.0)
line(x1, y1, x2, y2)                              // 1pt black line
strokeRect(x, y, w, h, width, r, g, b)            // Stroked rectangle, explicit width + color
strokeRectDashed(x, y, w, h, width, r, g, b, dash, phase)  // Dashed rectangle border
strokeLine(x1, y1, x2, y2, width, r, g, b)        // Line with explicit width + color
strokeLineDashed(x1, y1, x2, y2, width, r, g, b, dash, phase)  // Dashed line
textInRect(x, y, w, h, text, align)               // Lay text inside a rectangle (align 0/1/2)

布局辅助与终止操作

measure(text) -> number                  // Rendered width of text in the current font (points)
remainingSpace() -> number               // Vertical space left on the page (points)
newPageSameSize()                        // Start a new page with the same dimensions
table(spec)                              // Draw a buffered table from a spec object
streamingTable(spec) -> WasmStreamingTable  // Open a streaming table for large datasets
done(builder)                            // Commit this page's queued ops to the document builder

table(spec) 的 spec 对象采用 { columns: [{ header, width, align }], rows: [[...]], hasHeader } 结构。streamingTable(spec) 的 spec 在此基础上增加 { repeatHeader, mode, sampleRows, minColWidthPt, maxColWidthPt, maxRowspan, batchSize }。

---

WasmStreamingTable

由 WasmFluentPageBuilder.streamingTable(spec) 返回的逐行流式表格句柄。增量推入行，然后调用 finish()。

columnCount() -> number       // Number of columns
pendingRowCount() -> number   // Rows in the current un-flushed batch
batchCount() -> number        // Number of completed batches
pushRow(cells)                // Push one row (array of cell strings)
pushRowSpan(cells)            // Push a row whose cells may carry rowspans
flush()                       // Flush the current batch
finish()                      // Finalize the table and replay it into the page

---

WasmEmbeddedFont

通过 WasmDocumentBuilder.registerEmbeddedFont 注册以供嵌入的字体。

WasmEmbeddedFont.fromBytes(data, name?) -> WasmEmbeddedFont  // Load a TTF/OTF font from bytes
font.name -> string                                          // The font's resolved name (getter)

---

页面模板

跨页面应用的可复用页眉/页脚装饰。

WasmArtifactStyle

new WasmArtifactStyle()        // Default style
font(name, size) -> this       // Set font family and size
bold() -> this                 // Make the text bold
color(r, g, b) -> this         // Set the text color (RGB 0.0–1.0)

WasmArtifact

new WasmArtifact()                       // Empty artifact
WasmArtifact.left(text) -> WasmArtifact   // Left-aligned artifact text
WasmArtifact.center(text) -> WasmArtifact // Center-aligned artifact text
WasmArtifact.right(text) -> WasmArtifact  // Right-aligned artifact text
withStyle(style) -> this                  // Apply a WasmArtifactStyle
withOffset(offset) -> this                // Set the vertical offset from the edge

WasmHeader / WasmFooter

new WasmHeader()                  // Empty header (WasmFooter is identical)
WasmHeader.left(text) -> WasmHeader     // Left-aligned header text
WasmHeader.center(text) -> WasmHeader   // Center-aligned header text
WasmHeader.right(text) -> WasmHeader    // Right-aligned header text

WasmPageTemplate

new WasmPageTemplate()         // Empty template
header(header) -> this         // Set the page header artifact
footer(footer) -> this         // Set the page footer artifact
skipFirstPage() -> this        // Omit header/footer on the first page

---

数字签名

需要 signatures 特性。

WasmCertificate

WasmCertificate.load(data) -> WasmCertificate                  // Load a DER certificate + key bundle
WasmCertificate.loadPem(certPem, keyPem) -> WasmCertificate    // Load from PEM cert + key strings
WasmCertificate.loadPkcs12(data, password) -> WasmCertificate  // Load from a PKCS#12 (.p12/.pfx) blob
cert.subject -> string         // Subject distinguished name (getter)
cert.issuer -> string          // Issuer distinguished name (getter)
cert.serial -> string          // Serial number (getter)
cert.validity -> bigint[]      // [notBefore, notAfter] as unix seconds (getter)
cert.isValid -> boolean        // Whether the certificate is currently valid (getter)

WasmSignature

由 WasmPdfDocument.signatures() 返回。

sig.signerName -> string | null          // Signer common name (getter)
sig.reason -> string | null              // Signing reason (getter)
sig.location -> string | null            // Signing location (getter)
sig.contactInfo -> string | null         // Signer contact info (getter)
sig.signingTime -> bigint | null         // Signing time as unix seconds (getter)
sig.coversWholeDocument -> boolean       // Whether the signature covers the entire file (getter)
sig.padesLevel -> PadesLevel             // PAdES baseline level of the signature (getter)
sig.verify() -> boolean                  // Verify the signature cryptographically
sig.verifyDetached(pdfData) -> boolean   // Verify including a messageDigest check against the bytes

WasmTimestamp

WasmTimestamp.parse(data) -> WasmTimestamp  // Parse a DER TimeStampToken / TSTInfo
ts.time -> bigint              // Timestamp time as unix seconds (getter)
ts.serial -> string            // Serial number (getter)
ts.policyOid -> string         // TSA policy OID (getter)
ts.tsaName -> string           // TSA name (getter)
ts.hashAlgorithm -> number     // Imprint hash algorithm id (getter)
ts.messageImprint -> Uint8Array  // The message imprint digest (getter)
ts.verify() -> boolean         // Verify the timestamp token

WasmRevocationMaterial

供 signPdfBytesPades 使用的离线 PAdES-B-LT 校验材料。

new WasmRevocationMaterial()   // Empty material set
addCert(der)                   // Add a DER X.509 certificate
addCrl(der)                    // Add a DER CRL
addOcsp(der)                   // Add a DER OCSP response

Dss

由 WasmPdfDocument.dss() 返回的已解析文档安全存储 (Document Security Store)。

dss.certCount -> number        // Number of DER certificates (getter)
getCert(i) -> Uint8Array | undefined   // i-th DER certificate
dss.crlCount -> number         // Number of DER CRLs (getter)
getCrl(i) -> Uint8Array | undefined    // i-th DER CRL
dss.ocspCount -> number        // Number of DER OCSP responses (getter)
getOcsp(i) -> Uint8Array | undefined   // i-th DER OCSP response
dss.vri -> string[]            // Per-signature VRI keys (uppercase-hex SHA-1 of /Contents) (getter)

---

OCR

OCR 完全在 WASM 内运行，由独立的 wasm-ocr 构建中的纯 Rust tract 后端驱动。模型由宿主侧提供——先获取检测器/识别器的 ONNX 文件和字典（参见 modelManifest()），再将这些字节传给构造函数。

WasmOcrEngine

new WasmOcrEngine(detModel, recModel, dict, config?)  // Build from host-supplied model bytes
engine.ocrImage(imageBytes) -> string                 // OCR a raw image (PNG/JPEG/TIFF); returns JSON {text, confidence, spans}

参数	类型	描述
detModel	Uint8Array	DBNet 检测器 ONNX 字节
recModel	Uint8Array	SVTR 识别器 ONNX 字节
dict	string	识别器字符字典，每行一个字符
config	WasmOcrConfig | undefined	保留参数（使用经过调优的默认值）

WasmOcrConfig

new WasmOcrConfig()   // OCR configuration object (reserved for future tuning)

---

枚举

Align

textInRect 和表格列规格使用的文本/单元格对齐判别值。

Align.Left   // 0
Align.Center // 1
Align.Right  // 2

PadesLevel

PAdES 基线级别，由 signPdfBytesPades 和 WasmSignature.padesLevel 使用。

PadesLevel.BB    // 0 — signed attrs incl. ESS signing-certificate-v2
PadesLevel.BT    // 1 — B-B + RFC 3161 signature-time-stamp
PadesLevel.BLt   // 2 — B-T + Document Security Store (DSS/VRI)
PadesLevel.BLta  // 3 — B-LT + document-scoped /DocTimeStamp

---

功能可用性

部分功能受 Rust 构建特性控制。默认的 pdf-oxide-wasm 包启用了常用特性集；OCR 则随独立的 wasm-ocr 构建一起发布。

功能	WASM	说明
文本提取	支持	完整支持
结构化提取	支持	字符、span、单词、行、表格
创建 PDF	支持	Markdown、HTML、文本、图像、DocumentBuilder
编辑 PDF	支持	元数据、旋转、尺寸、擦除、页面
表单字段	支持	读取、写入、导出、扁平化、构建
搜索	支持	完整正则支持
加密	支持	AES-256 读取与写入
注释	支持	读取、扁平化、涂黑、清理
合并 / 拆分 PDF	支持	合并页面并按书签拆分
嵌入文件	支持	将文件附加到 PDF
页面标签 / XMP	支持	读取页面标签和 XMP 元数据
Office 往返转换	支持	DOCX/PPTX/XLSX 导入与导出
校验	支持	PDF/A、PDF/UA、PDF/X
条形码	支持 (barcodes)	1D + QR，输出 SVG 或页面图像
渲染	支持 (rendering)	页面 → PNG，扁平化为图像
数字签名	支持 (signatures)	签名、PAdES B-LT、验证、时间戳
OCR	wasm-ocr 构建	WASM 内的 tract OCR；模型由宿主侧获取

---

错误处理

所有可能失败的方法都会抛出 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");

---

Other Language Bindings

PDF Oxide 为所有主流生态系统提供原生绑定：Rust, Python, Node.js, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C, Elixir。

下一步

• 类型与枚举 — 所有共享类型与枚举
• Page API 参考 — 各绑定间一致的逐页迭代方式
• WASM 快速上手 — 教程