pdf.js 在线文档搜索插件：实现 PDF 关键词高亮与分页跳转

简介面向前端开发者与需要在网页中嵌入 PDF 阅读能力的项目团队这份资源提供了一套基于 pdf.js 的在线文档查看器插件可直接部署使用。它支持文档内关键词搜索并高亮命中结果、区分大小写匹配、分页翻页、页面放大缩小以及下载与打印等常用操作适合用于后台管理系统、资料库、合同或论文预览等场景对不熟悉 PDF 渲染底层的前端人员也较为友好。压缩包共 366 个文件约 5.53MB主体为 bcmap 字符映射表与 properties 配置配合 svg 图标、pfb 与 ttf 字体、少量 js 脚本、css 样式及 html 入口页面构成完整的查看器运行依赖。目前已有 359 人学习下载。借助现成的目录结构与可运行示例读者可快速替换 PDF 文件完成集成并在此基础上按需调整搜索高亮、分页与缩放等交互细节。1. 从一份“打不开的 PDF”说起这个插件到底解决什么问题很多后台系统里都有这么一幕用户上传了一份几十页的合同 PDF运营同事想在页面里直接搜一个条款关键词结果浏览器自带的 PDF 阅读器要么把搜索框藏在角落要么高亮一闪而过要么干脆整页跳转、上下文全丢。更麻烦的是业务方还要求“区分大小写”“搜到第几处要能翻页”“顺手能下载和打印”。这时候自己从零写一个 PDF 渲染器显然不现实而 pdf.js 这套在线文档搜索插件恰好就是冲着这个场景来的。它做的事情很具体把 PDF 文件在网页里渲染出来提供关键词搜索、命中高亮、大小写敏感开关、结果分页跳转再加上放大缩小、下载、打印这一套阅读器标配能力。适合谁适合那些需要在管理后台、知识库、合同系统里嵌一个“能搜能看”的 PDF 阅读器的前端开发者。你拿到源码后改的是工具栏和搜索逻辑底层渲染交给 pdf.js落地成本可控。2. 技术选型与目录结构为什么是 pdf.js 而不是别的方案2.1 选型逻辑渲染交给 pdf.js交互自己掌控这个项目的核心判断是“渲染归渲染交互归交互”。PDF 解析和 Canvas 绘制是重活pdf.js 已经把 PDF 语法解析、字体处理、分页渲染这些脏活干完了我们没必要重造。真正需要自己写的是搜索层拿到 PDF 的文本内容做关键词匹配再把命中位置映射回页面坐标做高亮。常见做法是直接用 pdf.js 的getTextContent()拿到每页的文本项每个文本项带str文本内容和transform变换矩阵后者决定了这段文字在页面上的位置。搜索时遍历所有页的文本项做字符串匹配命中后记录页码和坐标渲染时在 Canvas 上层叠一个绝对定位的高亮层。这样搜索和高亮就和渲染解耦了改搜索逻辑不用碰渲染代码。为什么不选浏览器原生 PDF 嵌入因为原生embed或iframe里的 PDF 阅读器是黑匣子你没法控制搜索高亮的样式也没法把“区分大小写”这种开关暴露给业务方。自己用 pdf.js 渲染虽然多写几百行但每个交互点都在自己手里二次开发时不用跟浏览器厂商的实现较劲。2.2 目录结构一个典型的前端插件工程源码包的结构大致是这样我按实际拆过的项目习惯还原一下pdf-search-viewer/ ├── src/ │ ├── core/ │ │ ├── pdf-loader.js # PDF 加载与页面渲染 │ │ ├── text-layer.js # 文本层提取与坐标映射 │ │ └── search-engine.js # 关键词搜索与命中记录 │ ├── ui/ │ │ ├── toolbar.js # 工具栏搜索框、缩放、下载、打印 │ │ ├── highlight.js # 高亮层绘制与滚动定位 │ │ └── pager.js # 搜索结果分页与页码跳转 │ ├── styles/ │ │ └── viewer.css # 阅读器与高亮样式 │ └── index.js # 插件入口暴露初始化 API ├── demo/ │ └── index.html # 本地演示页 ├── package.json └── README.md这个划分的关键在于core和ui分离。core里不碰 DOM 事件只负责“给我一个 PDF我告诉你每页有哪些文本、搜到了哪些位置”ui负责把搜索结果画出来、把工具栏按钮接上。二次开发时如果你只想换高亮颜色改styles/viewer.css和highlight.js就够了如果要换搜索算法比如加正则只动search-engine.js。2.3 依赖与构建pdf.js 的引入方式package.json里核心依赖就是pdfjs-dist。这里有个血泪经验pdf.js 的 worker 文件必须单独处理不能直接被打包器吞进去。常见做法是在入口处指定 worker 路径// src/index.js import * as pdfjsLib from pdfjs-dist; import PdfWorker from pdfjs-dist/build/pdf.worker.min.js?url; // 关键告诉 pdf.js 去哪里找 worker否则渲染会卡在主线程 pdfjsLib.GlobalWorkerOptions.workerSrc PdfWorker; export function createViewer(container, options {}) { // 初始化阅读器实例options 里可传初始缩放、是否默认区分大小写等 return new PdfSearchViewer(container, options); }workerSrc这一行是必须的。pdf.js 把解析工作放到 Web Worker 里跑主线程只负责绘制这样大文件渲染时页面不会假死。如果你用 Vite 或 Webpack?url这种写法能把 worker 文件作为静态资源输出路径才对得上。参数options里我一般会预留initialScale初始缩放比例默认 1.0、caseSensitive搜索是否默认区分大小写默认 false、highlightColor高亮底色这几个方便业务方初始化时定制。3. 核心模块拆解搜索、高亮、分页是怎么串起来的3.1 PDF 加载与页面渲染先把每一页画出来渲染是地基。pdf-loader.js的职责是拿到 PDF 文档对象按页渲染到 Canvas同时把每页的文本内容缓存下来供搜索用。// src/core/pdf-loader.js export class PdfLoader { constructor(pdfUrl) { this.pdfUrl pdfUrl; this.pdfDoc null; this.pages []; // 缓存每页的文本项搜索时直接读 } async load() { // 加载 PDF 文档getDocument 返回一个加载任务 const loadingTask pdfjsLib.getDocument(this.pdfUrl); this.pdfDoc await loadingTask.promise; return this.pdfDoc.numPages; // 返回总页数供分页器初始化 } async renderPage(pageNum, canvas, scale 1.0) { const page await this.pdfDoc.getPage(pageNum); // viewport 决定 Canvas 的实际像素尺寸scale 就是缩放比例 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; // 渲染完顺手把文本项缓存起来避免搜索时重复解析 if (!this.pages[pageNum]) { const textContent await page.getTextContent(); this.pages[pageNum] textContent.items; } return viewport; } }这段代码里有两个参数值得说清楚。scale直接决定渲染清晰度和 Canvas 尺寸放大缩小时就是改这个值重新渲染viewport是 pdf.js 根据页面原始尺寸和 scale 算出来的视口对象Canvas 的宽高必须跟它一致否则画面会拉伸。文本项缓存放在renderPage里做是因为渲染和取文本用的是同一个page对象顺手就拿了省一次解析。注意this.pages用页码做下标第 1 页存在pages[1]第 0 位空着遍历时从 1 开始。3.2 搜索与大小写敏感匹配逻辑落在文本项上搜索的核心在search-engine.js。它遍历缓存的文本项做字符串匹配命中后记录页码、文本项索引和字符偏移。// src/core/search-engine.js export class SearchEngine { constructor(pages, options {}) { this.pages pages; // 来自 PdfLoader 的文本项缓存 this.caseSensitive options.caseSensitive || false; } search(keyword) { if (!keyword) return []; const results []; // 区分大小写时保留原串否则统一转小写比较 const needle this.caseSensitive ? keyword : keyword.toLowerCase(); for (let pageNum 1; pageNum this.pages.length; pageNum) { const items this.pages[pageNum] || []; items.forEach((item, itemIndex) { const haystack this.caseSensitive ? item.str : item.str.toLowerCase(); let from 0; let idx; // 同一文本项里可能命中多次循环找全 while ((idx haystack.indexOf(needle, from)) ! -1) { results.push({ pageNum, itemIndex, charOffset: idx, length: keyword.length, text: item.str.substr(idx, keyword.length) }); from idx needle.length; } }); } return results; // 按页码、文本项顺序排列天然适合分页 } }逻辑说明caseSensitive为 true 时needle和haystack都保持原样indexOf就是严格匹配为 false 时两边都转小写实现大小写不敏感。charOffset记录命中在文本项内的字符位置后面高亮时要用它算宽度。length用原始关键词长度因为转小写不改变长度所以偏移和长度能对上。这里有个细节pdf.js 的文本项是按“文本块”切的一个词可能被切成多个 item跨 item 的关键词搜不到。常见做法是在搜索前把同一页相邻 item 的str拼一下做二次匹配但会牺牲坐标精度我一般先不做等业务方真提了再补。3.3 高亮绘制与滚动定位把命中位置画在 Canvas 上层搜到了还得让用户看见。highlight.js的做法是在每页 Canvas 外面套一个相对定位容器高亮层用绝对定位的div或span叠上去位置由文本项的transform矩阵换算。// src/ui/highlight.js export function renderHighlights(pageContainer, items, results, viewport) { // 清掉上一轮高亮避免叠加 pageContainer.querySelectorAll(.pdf-hit).forEach(el el.remove()); results.forEach(hit { const item items[hit.itemIndex]; // transform 是 [a,b,c,d,e,f]e/f 是文本项在页面坐标系的平移量 const tx item.transform[4]; const ty item.transform[5]; // 换算到 Canvas 像素坐标注意 PDF 坐标系 y 轴向上Canvas 向下 const left tx * viewport.scale; const top (viewport.height / viewport.scale - ty) * viewport.scale; const span document.createElement(span); span.className pdf-hit; span.style.left ${left}px; span.style.top ${top}px; // 宽度按字符偏移和字号估算字号从 transform 的缩放分量取 const fontSize Math.hypot(item.transform[2], item.transform[3]); span.style.width ${hit.length * fontSize * 0.6}px; span.style.height ${fontSize * viewport.scale}px; pageContainer.appendChild(span); }); }参数说明viewport.scale是当前缩放比例坐标换算必须乘它否则放大后高亮会错位transform[4]和transform[5]是文本项在 PDF 页面坐标系里的平移量PDF 原点在左下角、y 轴向上而 Canvas 原点在左上角、y 轴向下所以top要用页面高度减ty再换算。宽度用字符数 × 字号 × 0.6估算0.6 是个经验系数中英文混排时会有偏差真要精确得用measureText但那样每命中一次就测一次性能不划算。高亮层用pointer-events: none不然会挡住文本选择。3.4 结果分页与跳转搜到第 3 处视图就跟到第 3 处搜索结果可能几十上百条不能一次全画。pager.js负责把结果切片并提供“上一处/下一处”跳转。// src/ui/pager.js export class ResultPager { constructor(results, onJump) { this.results results; this.current 0; // 当前命中索引从 0 开始 this.onJump onJump; // 跳转回调由外部负责滚动和高亮当前项 } next() { if (this.current this.results.length - 1) { this.current; this.onJump(this.results[this.current], this.current); } return this.current; } prev() { if (this.current 0) { this.current--; this.onJump(this.results[this.current], this.current); } return this.current; } jumpTo(index) { if (index 0 index this.results.length) { this.current index; this.onJump(this.results[index], index); } } }onJump回调里做两件事把目标页滚动到视口内给当前命中项加一个区别于普通高亮的样式比如深色底。current是 0 基索引但界面上显示“第 3 / 20 处”时要加 1这个转换在工具栏里做别在分页器里混着改不然容易翻车。分页器不关心渲染细节只维护索引和回调这样换 UI 框架时它不用动。4. 跑起来与工具栏接线从 demo 到嵌入业务系统4.1 本地跑通三条命令看到效果拿到源码后先别急着改按 README 跑一遍 demo 确认环境没问题。# 安装依赖pdfjs-dist 是核心 npm install # 启动本地开发服务demo/index.html 会加载示例 PDF npm run dev # 如果要打包成可嵌入的库 npm run buildnpm run dev起来后打开demo/index.html应该能看到一个带工具栏的阅读器搜索框输入关键词能高亮点“下一处”会滚动定位。如果页面空白先看控制台有没有 worker 加载失败的报错十有八九是workerSrc路径不对。示例 PDF 一般放在demo/sample.pdf换成自己的文件时注意跨域本地开发用相对路径最稳。4.2 工具栏接线搜索框、缩放、下载、打印各管一摊toolbar.js是把 UI 事件翻译成核心模块调用的地方。搜索框回车触发search-engine缩放按钮改scale重渲染下载和打印走浏览器原生能力。// src/ui/toolbar.js export function bindToolbar(viewer, loader, engine) { const searchInput document.querySelector(#pdf-search); const caseToggle document.querySelector(#case-sensitive); const zoomIn document.querySelector(#zoom-in); const downloadBtn document.querySelector(#download); const printBtn document.querySelector(#print); searchInput.addEventListener(keydown, async (e) { if (e.key ! Enter) return; // 每次搜索前同步大小写开关状态 engine.caseSensitive caseToggle.checked; const results engine.search(searchInput.value.trim()); viewer.showResults(results); // 交给 pager 和 highlight 处理 }); zoomIn.addEventListener(click, () { viewer.setScale(viewer.scale 0.2); // 每次放大 0.2上限在 setScale 里卡 }); downloadBtn.addEventListener(click, () { // 直接用原始 PDF 地址触发下载不经过渲染层 const a document.createElement(a); a.href loader.pdfUrl; a.download document.pdf; a.click(); }); printBtn.addEventListener(click, () { // 打印前确保所有页已渲染否则打印出来是空白 viewer.renderAllPages().then(() window.print()); }); }逻辑说明搜索框只在回车时触发避免每敲一个字就全量搜一遍大文件下那样会卡。caseToggle.checked每次搜索前同步给引擎这样用户中途切换开关立即生效。缩放步长 0.2 是手感调出来的太小点着累太大容易跳。下载直接用原始 URL别去拼 Canvas 导出的图那样会丢矢量清晰度。打印前必须renderAllPages因为阅读器默认可能只渲染可视区域的几页直接window.print()打出来后面全是空白这个坑我踩过不止一次。4.3 嵌入业务系统初始化 API 怎么用插件入口暴露一个createViewer业务方拿到容器和 PDF 地址就能初始化// 业务页面里嵌入阅读器 import { createViewer } from pdf-search-viewer; const viewer createViewer(document.querySelector(#pdf-container), { pdfUrl: /files/contract-2024.pdf, initialScale: 1.2, // 初始缩放合同类文档字小可以调大 caseSensitive: true, // 合同条款搜索默认区分大小写 highlightColor: #ffe58f // 高亮底色跟业务主题走 });pdfUrl支持相对路径和绝对路径跨域文件需要服务端配 CORS。initialScale按文档类型调扫描件一般 1.0 就够排版密的合同调到 1.2 到 1.5。caseSensitive默认值看业务合同、代码类文档建议 true普通文章 false 更友好。初始化后返回的viewer实例上挂着setScale、showResults、renderAllPages这些方法业务方要做自定义按钮时直接调。5. 避坑与排查这五个坑我基本每次都遇到5.1 现象页面空白控制台报 worker 加载失败原因GlobalWorkerOptions.workerSrc没设或路径被构建工具改写了pdf.js 找不到 worker 就拒绝渲染。解决确认workerSrc指向实际可访问的.js文件Vite 下用?url导入Webpack 下用new URL(pdfjs-dist/build/pdf.worker.min.js, import.meta.url)打包后去dist里确认 worker 文件真的被输出了。5.2 现象放大后高亮位置整体偏移原因高亮坐标换算时用了旧的viewport.scale或者 Canvas 尺寸变了但高亮层没重算。解决缩放后先重渲染 Canvas拿到新viewport再调renderHighlights重画高亮两步顺序不能反。高亮层的父容器尺寸也要跟着 Canvas 同步否则绝对定位的基准就错了。5.3 现象跨文本块的关键词搜不到原因pdf.js 按文本块切 item一个词被切成两段时单 item 内indexOf匹配不上。解决搜索前把同一页相邻 item 的str拼接做二次匹配命中后按字符偏移反推落在哪几个 item 上高亮时分别画。代价是坐标精度下降长文档里可能出现高亮框略宽接受不了就只在单 item 内搜跟业务方说清楚限制。5.4 现象打印出来只有第一页有内容原因阅读器做了懒渲染只画了可视区域的页window.print()时其余页 Canvas 是空的。解决打印前调renderAllPages()把所有页渲染完再触发打印渲染是异步的要await。页数多时加个 loading 提示不然用户以为卡死了。5.5 现象区分大小写开关切了但结果没变原因caseSensitive只在引擎初始化时读了一次开关变化没同步。解决每次搜索前把caseToggle.checked赋给engine.caseSensitive或者给开关绑change事件主动触发重搜。别在引擎内部缓存这个值状态源头放在 UI 上引擎每次读最新值。6. 二次开发换搜索算法和接业务数据的几个改造点改造这个插件我一般从三个方向下手按改动成本从低到高排。第一个是换高亮样式和工具栏布局。styles/viewer.css里.pdf-hit控制普通命中.pdf-hit.current控制当前项改颜色、加圆角、换边框都在这。工具栏是普通 DOM业务方要加“全屏”“旋转”按钮在toolbar.js里绑事件、调viewer上对应方法就行不用碰核心模块。这个方向基本零风险适合先跑通再逐步替换。第二个是扩展搜索能力。search-engine.js的search方法目前是纯字符串匹配要加正则或全词匹配在这里改最合适。比如加一个useRegex选项// 在 search 方法里按选项分流 if (this.useRegex) { const re new RegExp(keyword, this.caseSensitive ? g : gi); // 用 re.exec 循环取 match.index 作为 charOffset } else { // 走原来的 indexOf 逻辑 }注意正则模式下charOffset用match.indexlength用match[0].length跟字符串模式对齐高亮层不用改。加完记得在工具栏暴露一个开关不然业务方用不上。第三个是接业务数据做联动。比如合同系统里用户点某条条款阅读器要自动跳到对应页并高亮。做法是业务方拿到条款的页码和关键词调viewer.jumpToPage(pageNum)再触发一次engine.search(keyword)取第一条结果定位。这里的关键是jumpToPage要等目标页渲染完再滚动否则滚到的是空白。我一般让它返回 Promise业务方await后再搜。验证改造是否成功我的习惯是准备三份测试 PDF一份纯文字合同测搜索和大小写、一份扫描件测渲染和缩放、一份超长文档测分页和打印。每次改完核心模块这三份都过一遍重点看高亮位置在缩放前后是否一致、打印是否全页有内容。这套流程是从一次线上事故后定下来的——当时只测了短文档长文档打印出来后半截全白被业务方追着问了一下午。从那以后我每次改渲染相关代码都强制走一遍“缩放→搜索→跳转→打印”的完整链路确认没回归才提交。希望帮到你。本文还有配套的精品资源点击获取