LibPDF文本提取深度指南:带位置信息与全文搜索的10种高阶用法

原创2026-10-10 13:50:411,855 阅读

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

📚 延伸阅读

一句话总结:LibPDF 的 PDF 文本提取 = 纯文本 + 坐标 + 搜索三合一。拿到 bbox 之后,搜索、定位、高亮、区域抓取全部水到渠成——这正是它区别于"只能抠字"的传统提取工具的地方。

登录后查看全文
core