基于pdf.js的PDF阅读器插件：搜索高亮与分页缩放实现

简介面向需要在网页端嵌入 PDF 阅读能力的开发者这份资源提供基于 pdf.js 的在线文档查看器插件可直接集成到项目中实现文档预览与交互操作。插件覆盖在线搜索并高亮命中结果、区分大小写匹配、分页翻页、页面放大缩小、文件下载与打印等常用功能适合前端工程师、后台管理系统开发者以及需要内嵌文档阅读模块的技术团队参考使用。压缩包共 366 个文件约 5.53MB以 bcmap 字符映射表、properties 本地化配置、svg 图标、pfb 与 ttf 字体、js 脚本及 css 样式为主另含示例 pdf 与许可说明构成一套可直接运行的完整查看器目录。已有 359 人学习下载。借助现成的目录结构与功能实现读者可快速搭建本地预览环境理解搜索高亮、大小写匹配与分页缩放等交互逻辑并在此基础上按需裁剪或扩展减少从零搭建 PDF 阅读器的时间成本。1. 从一份“能搜能标”的 PDF 阅读器说起很多项目里都会遇到同一个需求把 PDF 嵌进网页让用户能像看网页一样搜索关键词、高亮命中、翻页缩放最好还能下载和打印。听起来简单真动手才发现浏览器原生embed和iframe基本是个黑匣子搜索、高亮、分页这些能力全都没有。这个项目就是围绕 pdf.js 做的一层封装插件把在线搜索文档、高亮显示、区分大小写、分页、放大缩小、下载、打印这些功能一次性补齐。它适合两类人一类是手里有现成 PDF 文档站、需要快速加阅读器的开发者另一类是想基于 pdf.js 做二次开发、但不想从零啃渲染层的人。下面按“能干什么、怎么跑、怎么改”的顺序拆开讲。2. 技术选型与整体架构pdf.js 之上的一层薄封装2.1 为什么选 pdf.js 而不是浏览器原生预览浏览器自带的 PDF 预览器Chrome 的 PDF Viewer、Firefox 的 pdf.js 内置版能力其实不弱但它是“页面级”的你没法从外部拿到文本层、没法控制高亮、没法把搜索框接到自己的 UI 上。常见做法是直接用 pdf.js 的getDocument拿到 PDF 文档对象再自己渲染 canvas 和文本层。这个项目的思路也是这样底层用 pdf.js 负责解析和渲染上层用一层 JavaScript 封装出搜索、高亮、分页、缩放这些交互。选 pdf.js 的另一个原因是它纯前端、无服务端依赖PDF 文件放静态目录就能跑部署成本低。需要说明的是pdf.js 的文本层text layer是搜索和高亮的基础。它会把每一页的文字按坐标铺成透明的span你看到的“选中文字”其实是这些 span。搜索的本质就是遍历这些 span 的文本内容做匹配高亮则是给命中的 span 加背景色。理解这一点后面看代码就不会迷路。2.2 目录结构与模块职责这类插件的目录一般不会太深典型结构如下不同版本可能略有差异以实际源码为准pdf-viewer-plugin/ ├── index.html # 演示页挂载阅读器 ├── css/ │ └── viewer.css # 工具栏、高亮、分页样式 ├── js/ │ ├── main.js # 入口初始化、事件绑定 │ ├── pdf-loader.js # 封装 getDocument、加载进度 │ ├── renderer.js # canvas 文本层渲染 │ ├── search.js # 搜索、大小写、高亮 │ ├── toolbar.js # 分页、缩放、下载、打印 │ └── utils.js # 防抖、坐标换算等 ├── lib/ │ └── pdf.min.js # pdf.js 构建产物 └── assets/ └── sample.pdf # 示例文档pdf-loader.js只干一件事把 URL 或 ArrayBuffer 变成 pdf.js 的文档对象并暴露总页数。renderer.js负责把某一页画到 canvas 上同时生成文本层。search.js是功能核心处理关键词匹配和高亮。toolbar.js把按钮事件翻译成对 renderer 的调用。这种拆分的好处是搜索逻辑和渲染逻辑解耦改高亮样式不用动渲染代码。2.3 一次加载的完整链路从用户打开页面到看到第一页链路大致是main.js读取配置PDF 地址、初始页码、是否显示工具栏→ 调pdf-loader.js的loadPdf→getDocument返回pdfDoc→ 取getPage(1)→renderer用page.getViewport({ scale })算尺寸 → 画 canvas →page.getTextContent()拿文本项 → 生成文本层 span。这条链路里最容易出问题的是缩放后的坐标换算后面避坑章节会专门讲。提示pdf.js 的getDocument是异步的且大文件加载慢务必在 UI 上给加载进度否则用户会以为页面卡死。3. 核心功能拆解搜索、高亮与分页的实现细节3.1 搜索与区分大小写从文本层里捞关键词搜索的实现分两步先把当前页或全部页的文本项收集起来再做匹配。区分大小写就是一个开关决定匹配前是否toLowerCase()。下面是一段贴近项目实际的搜索核心代码// search.js async function searchInPage(page, keyword, caseSensitive) { const textContent await page.getTextContent(); const needle caseSensitive ? keyword : keyword.toLowerCase(); const hits []; textContent.items.forEach((item, index) { const haystack caseSensitive ? item.str : item.str.toLowerCase(); let pos haystack.indexOf(needle); // 一个文本项里可能命中多次全部记录下来 while (pos ! -1) { hits.push({ itemIndex: index, start: pos, length: keyword.length }); pos haystack.indexOf(needle, pos needle.length); } }); return hits; }这段代码的关键参数page是 pdf.js 的页面对象keyword是用户输入caseSensitive控制是否忽略大小写。item.str是文本项内容itemIndex用来回定位到文本层的 span。注意这里只做了单页搜索实际项目里通常再加一层循环遍历所有页并把结果按页分组方便“上一处/下一处”跳转。跨文本项的匹配关键词被拆在两个 span 里是常见难点简单做法是先按页拼接文本再匹配但高亮定位会变复杂多数插件选择不处理这种边界情况。3.2 高亮显示给命中的 span 加类名拿到命中位置后高亮不是直接改文本而是给对应的文本层 span 加一个 CSS 类。因为文本层 span 是 pdf.js 生成的顺序和textContent.items基本一一对应所以可以用itemIndex定位// search.js function highlightHits(container, hits) { // 先清掉上一次的高亮避免叠加 container.querySelectorAll(.pdf-hit).forEach(el { el.classList.remove(pdf-hit); }); hits.forEach(hit { const span container.querySelectorAll(.textLayer span)[hit.itemIndex]; if (span) span.classList.add(pdf-hit); }); }配套 CSS 很简单.pdf-hit { background: rgba(255, 235, 59, 0.6); }。这里有个细节如果同一个 span 里命中多次上面的写法只能整体高亮做不到“只标关键词那几个字”。要做到字符级高亮得把 span 拆成三段前、命中、后再分别包元素代码量会翻倍。项目里如果只要求“整段标黄”当前写法够用要求精确到字就得走拆分方案。3.3 分页与缩放viewport 是唯一真相分页本质是切换当前页码后重新渲染。缩放则是改scale后重算 viewport。核心代码// renderer.js async function renderPage(pdfDoc, pageNum, scale, canvas, textLayerDiv) { const page await pdfDoc.getPage(pageNum); const viewport page.getViewport({ scale }); const ctx canvas.getContext(2d); canvas.width viewport.width; canvas.height viewport.height; await page.render({ canvasContext: ctx, viewport }).promise; // 文本层按同样 viewport 生成保证坐标对齐 const textContent await page.getTextContent(); textLayerDiv.style.width ${viewport.width}px; textLayerDiv.style.height ${viewport.height}px; // 这里通常调用 pdf.js 的 renderTextLayer 或手动铺 span }参数说明scale是缩放倍数1 表示原始尺寸viewport决定了 canvas 像素尺寸和文本层容器尺寸两者必须用同一个 viewport否则文字和画面会错位。分页时只需把pageNum换成目标页再调一次renderPage。缩放时建议加防抖连续点“放大”不要每次都重渲染等用户停手再画。3.4 下载与打印别自己造轮子下载最省事的做法是直接用原始 PDF 的 URL 触发a download不需要经过 pdf.js。打印则有两种思路一是调window.print()配合打印样式二是用 pdf.js 把页面渲染成图片再拼打印页。前者简单但依赖浏览器打印对话框后者可控但代码多。项目里如果只是“能打印”window.print()加一段media print隐藏工具栏就够了media print { .toolbar, .search-bar { display: none !important; } canvas { page-break-after: always; } }注意打印时 canvas 是位图分辨率不够会糊。需要高清打印的话打印前用更高scale重渲染一遍再调window.print()。4. 跑起来与改造前必看的避坑清单4.1 本地起服务别直接双击 HTMLpdf.js 加载 PDF 走的是 fetch/XHRfile://协议下大概率被浏览器拦截表现为控制台报跨域或加载失败。正确姿势是在项目根目录起一个静态服务# 任选一种Python 自带的最省事 python3 -m http.server 8080 # 或者 npx serve .然后访问http://localhost:8080。如果 PDF 放在别的域名记得服务端配 CORS否则getDocument会失败。4.2 文本层错位viewport 不一致是元凶现象放大后文字选中区域和画面对不上或者高亮块飘到别处。原因几乎都是 canvas 用的 viewport 和文本层容器用的尺寸不是同一个 scale 算出来的。解决方法是把 viewport 算一次、存下来canvas 和文本层都从它取值不要各自调getViewport。另外文本层 span 的定位依赖 pdf.js 的renderTextLayer手动铺 span 时 transform 矩阵不能省。4.3 搜索卡顿全量遍历要加节流现象文档几百页时输入关键词页面直接卡住。原因是每次输入都遍历所有页的getTextContent。解决输入加 300ms 防抖文本内容按页缓存第二次搜索直接读缓存只搜当前页或可视范围提供“全文档搜索”按钮让用户主动触发。4.4 高亮残留切换页面没清理现象翻到下一页上一页的高亮类名还在或者同一位置叠了好几层。原因是高亮加在 span 上重渲染后旧 span 被替换但类名逻辑没重置。解决每次renderPage前清空文本层容器或者在高亮函数入口统一querySelectorAll(.pdf-hit)移除。这个坑很隐蔽因为 DOM 被替换后视觉上可能看不出来直到你做“上一处/下一处”跳转才发现索引错乱。4.5 打印空白页canvas 没等渲染完现象点打印预览里是空白或只有第一页。原因是window.print()在 canvas 渲染完成前就触发了。解决打印前await所有页渲染完成或者监听渲染 promise 再调打印。另一个常见原因是打印样式把 canvas 设成了display: none检查media print里有没有误伤。5. 二次开发把插件改成你自己的阅读器5.1 先定改造边界再动代码拿到这份源码别急着改 UI。先想清楚你要的是“换皮”还是“换骨”。换皮只动viewer.css和toolbar.js的按钮布局换骨比如要支持批注、书签、双页模式就得动renderer.js和search.js的数据结构。我的习惯是先跑通示例 PDF确认搜索、缩放、打印都正常再建一个分支做改造避免一上来就改得跑不起来。5.2 三个高频改造点与验证方法第一个是搜索范围。默认单页搜索改成全文档搜索改动点在search.js外层加页循环验证方法是拿一份 50 页以上、关键词分布在不同页的 PDF看“下一处”能否跨页跳转。第二个是高亮精度。整段标黄改成字符级需要拆 span验证时重点看同一段里出现两次关键词是否都能单独标出。第三个是移动端适配。工具栏在窄屏会挤常见做法是折叠成图标菜单验证用浏览器设备模拟即可。改造点改动文件验证要点全文档搜索search.js跨页跳转、结果计数准确字符级高亮search.js viewer.css同段多次命中分别高亮移动端工具栏toolbar.js viewer.css375px 宽度下按钮不溢出5.3 一个容易忽略的细节页码与滚动同步如果要做“滚动加载所有页”而不是“单页翻页”页码和滚动位置的同步是个技术活。常见做法是监听滚动用每页容器的offsetTop判断当前可视页再更新工具栏页码。这里别用固定高度估算PDF 每页高度可能不同必须读实际 DOM 高度。我在这上面翻过车早期用平均高度算结果长页文档页码全乱后来改成遍历页容器取getBoundingClientRect才稳。5.4 收尾的一点经验改造这类基于 pdf.js 的插件最省时间的路径永远是“先让官方示例跑通再一处一处替换”。我现在的习惯是每改一个功能就先跑一遍示例 PDF确认搜索、缩放、打印三条主链路没断再继续下一个。血泪经验是文本层和高亮相关的改动最容易引入玄学错位改完一定用放大到 200% 的状态检查一遍对齐。希望这份拆解能帮你少走几步弯路把这份插件真正用进自己的项目里。本文还有配套的精品资源点击获取