SuperAPI AI 工具集

pdfjs-syntax-text-layer

编程与开发

查看项目

更新于 11-11 10:55

技能介绍

用途

该技能面向使用 PDF.js(pdfjs-dist)的开发者,解决两类任务:

  1. 在已渲染的 PDF 页面 canvas 之上叠加可选择、可搜索的文本层(text layer),让用户能够像操作普通网页文本一样选中、复制和搜索 PDF 中的文字。
  2. 从 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 位置。

使用方式

技能文档给出了分步管线:

  1. 使用 page.render({ canvasContext, viewport }) 将页面渲染到 canvas。
  2. 使用 page.getTextContent() 获取文本内容。
  3. 创建一个绝对定位覆盖在 canvas 上的容器 div。
  4. 使用 new TextLayer({ textContentSource, container, viewport }) 创建实例。
  5. 调用 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