LibPDF文本提取深度指南:带位置信息与全文搜索的10种高阶用法
LibPDF文本提取深度指南:带位置信息与全文搜索的10种高阶用法
LibPDF 是一款现代 TypeScript PDF 处理库(项目名 core),其 PDF 文本提取 功能不只是"把文字抠出来":每个字符都带有精确的坐标位置(bbox),并原生支持全文搜索、正则匹配与命中高亮。对于新手和普通用户,这意味着你可以用它做 PDF 关键词检索、表单数据定位、模板占位符标记,甚至给命中文本画框——全程不需要任何第三方 OCR 工具。
本指南将带你掌握 10 种带位置信息与全文搜索的高阶用法,每种都配有可运行的示例文件,照着做即可上手。
🚀 快速开始:三步拿到 PDF 文本
只需两行代码,就能从 PDF 页面中拿到纯文本:
const page = pdf.getPage(0);
const { text } = page.extractText();
提取结果按阅读顺序(从上到下、从左到右)排列。核心实现位于 src/text/text-extractor.ts,文本自动按行分组的逻辑在 src/text/line-grouper.ts。
| 功能 | 核心 API | 典型场景 |
|---|---|---|
| 纯文本提取 | page.extractText() |
全文备份、送 AI 分析 |
| 位置信息 | lines[].bbox |
区域提取、屏幕坐标换算 |
| 全文搜索 | page.findText() |
关键词检索、高亮定位 |
| 正则搜索 | page.findText(/正则/g) |
抽取邮箱、编号、模板标签 |
一、基础提取:从文本到坐标
1️⃣ 单页纯文本提取
extractText() 返回 PageText 结构,其中 text 字段就是拼接好的纯文本字符串。完整可运行示例见 examples/12-text-extraction/extract-text.ts。
2️⃣ 全文档多页提取
不想一页页遍历?直接对文档对象调用:
const allPages = pdf.extractText(); // 每页一条记录,含 pageIndex
每个结果都带有 pageIndex,方便后续按页定位。大文档建议逐页处理并及时释放内存,性能技巧详见官方指南 content/docs/guides/text-extraction.mdx。
3️⃣ 带位置信息的文本提取(重点)
PageText.lines 提供每行的包围盒 bbox(x、y、width、height),行内再按字体切分为 spans,每个 span 还带逐字符位置。数据结构定义在 src/text/types.ts。
⚠️ 新手必知的坐标陷阱:PDF 坐标系原点在左下角,y 轴向上。若要在屏幕或画布上渲染,需换算:screenY = 页面高度 - bbox.y - bbox.height。
4️⃣ 读取字号与字体名
每个 span 都带 fontSize 和 fontName,这对识别标题层级、区分正文字号非常有用:
for (const line of pageText.lines) {
for (const span of line.spans) {
console.log(span.text, span.fontSize, span.fontName);
}
}
5️⃣ 按区域提取指定位置的文字
有了 bbox,"只取某个矩形区域内的文字"就变成一次简单的过滤——比如只提取发票右上角的发票号、或只读侧栏注释。官方指南中给出了完整的区域过滤写法(content/docs/guides/text-extraction.mdx 的 "Extract by Region" 一节)。
二、全文搜索:从关键词到正则高亮
6️⃣ 基础全文搜索 findText
在单页中查找一个字符串,返回所有命中位置(含 bbox 和页码):
const matches = page.findText("invoice");
搜索核心实现在 src/text/text-search.ts,完整示例见 examples/12-text-extraction/search-text.ts。
7️⃣ 大小写不敏感 + 整词匹配
两个常用开关:
page.findText("lorem", { caseSensitive: false }); // 忽略大小写
page.findText("et", { wholeWord: true }); // 只匹配完整单词
wholeWord: true 能避免搜 "et" 时把 "consectetuer" 也误命中,对中文分词场景之外的英文检索特别实用。
8️⃣ 正则搜索:抽取邮箱、发票号、模板标签
findText 直接接受正则表达式,这是它最"高阶"的能力:
const invoices = page.findText(/INV-\d{6}/g); // 发票编号
const emails = page.findText(/[\w.-]+@[\w.-]+\.\w+/g); // 邮箱
const tags = page.findText(/\{\{\s*\w+[^}]*\}\}/g); // {{模板标签}}
每个命中结果都附带 bbox,也就是说搜索即定位。
9️⃣ 全文档跨页搜索
对文档对象调用即可跨所有页搜索,结果自带 pageIndex:
const hits = pdf.findText("volutpat");
console.log(hits.map(h => `第${h.pageIndex + 1}页: "${h.text}"`));
🔟 给命中位置画框高亮(搜索 + 绘制的组合技)
将第 8️⃣ 步的正则结果与绘制 API 组合,就能给模板占位符自动描边——文档自动化、模板校验的杀手级应用:
for (const match of page.findText(/\{\{[^}]+\}\}/g)) {
page.drawRectangle({
x: match.bbox.x - 2, y: match.bbox.y - 2,
width: match.bbox.width + 4, height: match.bbox.height + 4,
borderColor: rgb(0.8, 0.2, 0.2), borderWidth: 2,
});
}
完整可运行示例:examples/12-text-extraction/highlight-template-tags.ts。
⚠️ 常见问题与已知限制
| 现象 | 原因 | 解决办法 |
|---|---|---|
| 提取出乱码(含 \uFFFD) | PDF 缺少 ToUnicode 映射 | PDF 本身必须包含字体映射 |
| 提取结果为空 | 文字其实是图片 | 需借助外部 OCR 工具 |
| 阅读顺序错乱 | 复杂多栏排版 | 用 bbox 位置数据自行重排 |
| 缺失部分中日韩文字 | 预定义 CMap 限制 | 目前仅支持 Identity-H/V |
📚 延伸阅读
- 文本提取官方指南:content/docs/guides/text-extraction.mdx
- 完整 API 参考(
extractText/findText):content/docs/api/pdf-page.mdx - 类型定义(BoundingBox / PageText / TextMatch):src/text/types.ts
- 更多示例:examples/12-text-extraction/
一句话总结:LibPDF 的 PDF 文本提取 = 纯文本 + 坐标 + 搜索三合一。拿到 bbox 之后,搜索、定位、高亮、区域抓取全部水到渠成——这正是它区别于"只能抠字"的传统提取工具的地方。