用途
该技能面向使用 PDF.js(pdfjs-dist)的开发者,解决两类任务:
- 在已渲染的 PDF 页面 canvas 之上叠加可选择、可搜索的文本层(text layer),让用户能够像操作普通网页文本一样选中、复制和搜索 PDF 中的文字。
- 从 PDF 页面中提取纯文本内容,或获取文本项的位置信息。
主要能力
- 文本层渲染:使用
TextLayer类构造函数与render()方法创建文本层,替代在 pdfjs-dist 5.x 中已被移除的renderTextLayer()函数。 - 文本内容获取:通过
page.getTextContent()获取TextContent对象,遍历items中的TextItem拼接文本行。 - 流式文本提取:通过
page.streamTextContent()返回ReadableStream,适用于大文档,避免一次性将全部文本内容加载到内存。 - 缩放/旋转更新:通过
textLayer.update({ viewport })重新定位已有文本 span,无需重建文本层。 - 清理与取消:通过
textLayer.cancel()取消进行中的渲染,通过TextLayer.cleanup()在全部文本层销毁后清理全局缓存。 - 坐标信息:
TextItem.transform矩阵中的transform[4]和transform[5]分别对应 x、y 位置。
使用方式
技能文档给出了分步管线:
- 使用
page.render({ canvasContext, viewport })将页面渲染到 canvas。 - 使用
page.getTextContent()获取文本内容。 - 创建一个绝对定位覆盖在 canvas 上的容器 div。
- 使用
new TextLayer({ textContentSource, container, viewport })创建实例。 - 调用
textLayer.render()将文本 span 写入 DOM。
关键注意事项包括:
- 文本层容器必须使用
position: absolute直接覆盖在 canvas 上,否则文本选择坐标无法与渲染内容对齐。 - 文本层容器的 CSS 尺寸必须与 canvas 一致,尺寸不匹配会导致文本 span 偏移。
- 文本层容器设置
pointer-events: none,单个文本 span 设置pointer-events: all,以便无文本区域可点击穿透到 canvas,同时保留文本选择能力。 - 必须引入 PDF.js 文本层 CSS(如
pdfjs-dist/web/pdf_viewer.css或等价自定义样式),否则文本 span 会以可见黑字显示在 canvas 上方,而不是透明的可选覆盖层。 - 同一页面在缩放/旋转等场景重新创建文本层前,必须先调用
textLayer.cancel(),否则会产生重复文本 span 和内存泄漏。 - 在生产环境中应引入
pdfjs-dist/web/pdf_viewer.css完整样式,而不是维护自定义最小 CSS。
适用场景
- 需要在 Web 应用中展示 PDF 并支持文字选择、复制、搜索的阅读器。
- 需要从 PDF 页面抽取文本做索引、搜索或后续处理的场景。
- 需要获取 PDF 文本位置坐标以实现高亮或标注的场景。
- 处理大文档时希望流式读取文本内容以控制内存占用的场景。
限制
- 技能内容针对 pdfjs-dist 5.x,旧版本 API 行为可能不同。
- 文档未提供对 PDF 加密、扫描件 OCR、字体嵌入异常等特殊情况的处理说明,这些情况暂未提供。
- 文档未提供性能基准数据或浏览器兼容性列表,暂未提供。
参考资源
- PDF.js API 参考:https://mozilla.github.io/pdf.js/api/
- TextLayer 源码:https://github.com/mozilla/pdf.js/blob/master/src/display/text_layer.js
- 官方示例:https://github.com/mozilla/pdf.js/tree/master/examples
- 技能内附参考文件:references/methods.md、references/examples.md、references/anti-patterns.md