1. 项目背景与核心需求

最近在重构一个后台管理系统，产品经理提了个需求，要求在用户中心模块里，能直接在线预览用户上传的PDF格式的合同或协议文件。这个需求听起来很常规，对吧？但真动手做的时候，你会发现，在前端、特别是Vue生态里，实现一个稳定、体验好的PDF预览功能，远不止是加个<iframe>标签那么简单。

用户上传的PDF文件，可能来自不同设备、不同软件生成，大小从几十KB到几十MB不等。如果直接让用户下载到本地再用阅读器打开，体验是割裂的，而且无法控制文件的传播。我们需要的是一个内嵌的、无需跳转的、支持基础交互的预览方案。核心诉求可以拆解为以下几点：第一，零依赖，用户无需安装任何插件（比如古老的Adobe Reader插件）；第二，性能可控，对于大文件要有加载策略，不能直接拖垮页面；第三，功能完备，至少支持缩放、翻页、搜索文本（如果能做到的话）；第四，与Vue技术栈无缝集成，维护起来方便。

市面上常见的方案有好几种，比如使用<iframe>、<embed>标签，或者利用浏览器原生能力如window.open()，再或者使用PDF.js这个Mozilla出品的强大库。<iframe>方案最简单，但定制能力弱，样式隔离严重，且无法精细控制加载过程。PDF.js功能最强大，几乎是行业标准，但直接使用其原生API略显繁琐，需要自己处理渲染、分页、工具栏等一堆事情。

这时候，基于PDF.js封装的Vue组件库就成了一个非常自然的选择。它们帮我们封装了底层的复杂性，提供了声明式的Vue组件，让我们能用写Vue组件的方式，快速搭建一个PDF预览器。在众多选择中，vue-pdf和pdfvuer是比较流行的两个。这次我重点聊聊vue-pdf，因为它相对更轻量，API也直观，适合快速集成基础预览功能。当然，这并不意味着它是唯一解，在文章后面我也会对比一下其他方案的适用场景。

2. 技术选型：为什么是 vue-pdf？

面对一个功能需求，选择用什么技术来实现，本质上是在做权衡。为什么在这个场景下，我倾向于选择vue-pdf，而不是其他方案？我们来做个简单的对比分析。

首先，最原始的<iframe src=”your-file.pdf”>。它的优点是简单到极致，一行代码搞定，浏览器原生支持。但缺点也同样明显：它是一个完全独立的浏览上下文，你几乎无法与其内部进行任何交互（比如监听页面加载事件、捕获错误），样式也无法穿透，那个丑丑的浏览器原生PDF工具栏你可能无法隐藏或替换。对于只需要“能看就行”的简单场景，它或许可以，但对于一个追求体验和可控性的现代Web应用，它首先被排除。

其次，直接使用PDF.js。这是功能最全面、最强大的方案，PDF.js本身就是一个完整的PDF渲染引擎，提供了从解析、渲染到交互的全套底层API。如果你需要实现极其定制化的预览器，比如复杂的标注、合并页面、高级文本提取，那么直接使用PDF.js是必经之路。但它的代价是较高的集成复杂度。你需要手动管理PDFJS.GlobalWorkerOptions.workerSrc（指向PDF.js的worker文件），自己写代码来获取文档、渲染页面到canvas、处理缩放和翻页逻辑，还要自己打造一个用户界面（工具栏）。这对于一个以业务开发为主、需要快速上线的项目来说，初始成本太高。

于是，基于PDF.js的Vue封装组件应运而生。vue-pdf和pdfvuer都属于这一类。它们把PDF.js的核心能力包装成Vue组件，提供了诸如<pdf>、<pdf-viewer>这样的标签，让我们可以通过传递src、page等props，以及监听@loaded、@error等事件，以声明式的方式控制PDF预览。这极大地提升了开发效率。

那么，vue-pdf和pdfvuer之间怎么选？我简单梳理了一下：

• vue-pdf: 更轻量，更专注于“渲染PDF页面”这个核心功能。它的主要组件是<pdf>，用于渲染单页，你需要自己组合分页、缩略图、工具栏等外围功能。这种设计给了开发者更大的灵活性，你可以按需组装自己需要的预览器形态。文档相对简洁，学习曲线平缓。
• pdfvuer: 功能更集成化，提供了一个功能相对完整的<pdf-viewer>组件，内部集成了分页控件、缩放控件等。如果你想快速得到一个开箱即用、功能相对齐全的预览窗口，pdfvuer可能更省事。但相应地，它的定制性可能不如vue-pdf灵活，且包体积可能略大。

基于我们项目的需求——需要内嵌预览、需要自定义工具栏样式、需要精细控制加载状态和错误处理，并且我们对预览器的UI有统一的设计规范——vue-pdf这种“提供核心渲染能力，外围功能自己组装”的模式更匹配。它让我们能够以较低的成本获得PDF.js的强大渲染能力，同时又保留了UI层的完全控制权。这就是选择vue-pdf的核心原因：在能力、效率和控制力之间取得了不错的平衡。

3. 环境准备与 vue-pdf 基础集成

确定了技术方案，接下来就是动手集成。整个过程可以概括为：安装、引入、配置、使用四步。但每一步里都有些细节需要注意，否则很容易踩坑。

3.1 安装依赖

首先，在你的Vue项目中安装vue-pdf。它依赖于PDF.js，所以会一并安装。

npm install vue-pdf --save # 或 yarn add vue-pdf

安装完成后，你可以在package.json里看到类似”vue-pdf”: “^4.3.0″的依赖（版本号可能不同）。

这里有个关键点：vue-pdf内部引用了PDF.js的特定版本。有时，如果你项目里同时存在其他也依赖PDF.js的库，可能会引发版本冲突。虽然不常见，但如果你遇到一些诡异的渲染错误，可以检查一下node_modules里pdfjs-dist的版本是否唯一。

3.2 全局引入与组件注册

vue-pdf默认导出了一个pdf组件。我们可以在需要使用的页面或组件里局部引入，也可以在全局注册以便在任何地方使用。对于后台管理系统这种多个模块都可能用到PDF预览的场景，我推荐全局注册。

在你的主入口文件（通常是main.js或main.ts）中，添加以下代码：

import Vue from ‘vue‘; import pdf from ‘vue-pdf‘; Vue.component(‘pdf‘, pdf);

这样，你就可以在整个项目的任何Vue模板中直接使用<pdf>标签了。

3.3 核心组件与基础用法

vue-pdf的核心是<pdf>组件。它的基本用法非常简单，通过:src属性绑定PDF文件的源。

<template> <div> <pdf :src=”pdfUrl”></pdf> </div> </template> <script> export default { data() { return { pdfUrl: ‘/api/files/contract.pdf‘, // 可以是相对路径、绝对URL或Blob URL }; }, }; </script>

这样，一个最基础的PDF预览就完成了。组件会自动加载PDF文件，并渲染第一页。

但是，这仅仅是个开始。一个完整的预览器还需要处理很多情况：

1. 多页文档：上面的写法只会显示第一页。PDF通常是多页的。
2. 加载状态：网络文件加载需要时间，需要给用户一个加载提示。
3. 错误处理：文件可能不存在、格式错误或网络出错。
4. 交互控制：如何翻页、缩放？

<pdf>组件提供了一系列的props和events来支持这些功能。我们先看看它常用的属性：

以及几个关键事件：

• @loaded：当PDF文档总页数信息加载完成时触发。回调参数包含总页数(totalPages)等信息。这是获取总页数的唯一可靠时机。
• @page-loaded：当某一页渲染完成时触发。回调参数包含当前页码(page)等信息。
• @page-size：当获取到某一页的尺寸时触发。
• @error：当加载或渲染过程中发生错误时触发。回调参数是错误对象。
• @password：当需要密码解密时触发。

基于这些，我们可以构建一个更健壮的基础预览组件。

4. 构建一个完整的PDF预览组件

现在，我们利用<pdf>组件提供的能力，从头构建一个具备分页、缩放、加载提示和错误处理的基础预览器。这个组件将包含工具栏和内容区。

4.1 组件结构与数据设计

我们创建一个名为PdfViewer.vue的单文件组件。

<template> <div class=”pdf-viewer”> <!-- 工具栏 --> <div class=”toolbar” v-if=”!loading && !error”> <button @click=”prevPage” :disabled=”currentPage <= 1″>上一页</button> <span>{{ currentPage }} / {{ totalPages }}</span> <button @click=”nextPage” :disabled=”currentPage >= totalPages”>下一页</button> <select v-model=”scale” @change=”onScaleChange”> <option value=”0.5″>50%</option> <option value=”0.75″>75%</option> <option value=”1″ selected>100%</option> <option value=”1.25″>125%</option> <option value=”1.5″>150%</option> <option value=”2″>200%</option> </select> <button @click=”rotatePage”>旋转</button> </div> <!-- 加载状态 --> <div class=”loading” v-if=”loading”> 正在加载PDF文档… </div> <!-- 错误状态 --> <div class=”error” v-if=”error”> 加载失败: {{ errorMessage }} <button @click=”retryLoad”>重试</button> </div> <!-- PDF渲染区域 --> <div class=”pdf-container” v-if=”!loading && !error”> <pdf ref=”pdfRef” :src=”pdfSource” :page=”currentPage” :rotate=”rotate” :scale=”scale” @loaded=”onPdfLoaded” @page-loaded=”onPageLoaded” @error=”onPdfError” ></pdf> </div> </div> </template>

在这个模板中，我们定义了：

• 一个工具栏，包含翻页按钮、页码显示、缩放下拉框和旋转按钮。工具栏仅在加载成功后才显示。
• 加载中和错误状态提示区域。
• PDF渲染区域，使用<pdf>组件，并绑定了多个状态和事件。

在<script>部分，我们需要定义相应的数据和逻辑：

<script> import pdf from ‘vue-pdf‘; export default { components: { pdf }, props: { // 接收外部传入的PDF源，可以是URL或Blob等 src: { type: [String, Object, Blob, ArrayBuffer], required: true, }, }, data() { return { currentPage: 1, // 当前页码 totalPages: 0, // 总页数 scale: 1, // 缩放比例 rotate: 0, // 旋转角度 loading: true, // 加载状态 error: false, // 错误状态 errorMessage: ‘‘, // 错误信息 pdfSource: null, // 实际传递给pdf组件的源 }; }, watch: { // 监听外部传入的src变化，重新加载 src: { immediate: true, handler(newVal) { this.loadPdf(newVal); }, }, }, methods: { // 加载PDF的核心方法 loadPdf(src) { this.loading = true; this.error = false; this.errorMessage = ‘‘; this.totalPages = 0; this.currentPage = 1; // 这里可以对src进行预处理，比如如果是相对路径，可以拼接基础URL // 假设我们直接使用传入的src this.pdfSource = src; // 注意：pdfSource赋值后，pdf组件会自动开始加载并触发@loaded事件 }, // PDF文档加载完成事件 onPdfLoaded(pdfInfo) { this.loading = false; this.totalPages = pdfInfo.numPages; // 从回调参数中获取总页数 console.log(`PDF加载完成，共${this.totalPages}页`); }, // 单页渲染完成事件 onPageLoaded(pageInfo) { console.log(`第${pageInfo.pageNumber}页渲染完成`); }, // PDF加载或渲染错误事件 onPdfError(err) { this.loading = false; this.error = true; this.errorMessage = err.message || ‘未知错误‘; console.error(‘PDF加载失败:‘, err); }, // 工具栏方法 prevPage() { if (this.currentPage > 1) { this.currentPage -= 1; } }, nextPage() { if (this.currentPage < this.totalPages) { this.currentPage += 1; } }, onScaleChange() { // 缩放比例改变，pdf组件会自动响应 console.log(`缩放比例变更为: ${this.scale}`); }, rotatePage() { this.rotate = (this.rotate + 90) % 360; // 每次点击旋转90度 }, retryLoad() { this.loadPdf(this.src); }, }, }; </script>

最后，添加一些基础样式让布局更美观：

<style scoped> .pdf-viewer { border: 1px solid #dcdfe6; border-radius: 4px; overflow: hidden; } .toolbar { padding: 10px; background-color: #f5f7fa; border-bottom: 1px solid #dcdfe6; display: flex; align-items: center; gap: 10px; } .pdf-container { padding: 20px; text-align: center; min-height: 500px; display: flex; justify-content: center; align-items: flex-start; background-color: #fff; } .loading, .error { padding: 40px; text-align: center; color: #909399; } .error { color: #f56c6c; } </style>

现在，一个功能完整的PDF预览组件就完成了。你可以像这样使用它：

<template> <div> <PdfViewer :src=”pdfFileUrl” /> </div> </template> <script> import PdfViewer from ‘@/components/PdfViewer.vue‘; export default { components: { PdfViewer }, data() { return { pdfFileUrl: ‘https://example.com/sample.pdf‘, }; }, }; </script>

4.2 处理不同格式的PDF源

在实际业务中，PDF文件的来源多种多样。vue-pdf的:src属性支持多种类型，但处理方式略有不同。

1. 远程URL：最常见的情况。直接传入完整的HTTP/HTTPS地址即可。但要注意跨域问题。如果PDF文件存储在另一个域名下，需要确保该服务器配置了正确的CORS（跨域资源共享）头，否则浏览器会阻止加载。

   pdfSource: ‘https://api.your-domain.com/files/123.pdf‘

2. 本地相对路径/项目内静态资源：将PDF文件放在项目的public或static目录下，然后使用相对路径。在开发和生产环境下，Vue CLI会正确处理这些路径。

   // 假设文件放在 public/docs/guide.pdf pdfSource: ‘/docs/guide.pdf‘

3. 后端API返回的二进制流（Blob/ArrayBuffer）：这是更常见的场景。前端通过Axios等库调用后端接口获取文件流。

   async fetchPdf() { this.loading = true; try { const response = await axios.get(‘/api/download/contract‘, { responseType: ‘blob‘, // 关键！指定响应类型为blob params: { id: this.fileId }, }); // 将Blob对象直接赋值给src this.pdfSource = response.data; // 或者，也可以创建Object URL（注意内存释放） // const blobUrl = URL.createObjectURL(response.data); // this.pdfSource = blobUrl; // 在组件销毁时，需要调用 URL.revokeObjectURL(blobUrl) 释放内存 } catch (err) { this.onPdfError(err); } }

   重要提示：使用Blob或ArrayBuffer时，vue-pdf内部会进行处理。如果使用URL.createObjectURL创建临时URL，务必在组件销毁前调用URL.revokeObjectURL()来释放内存，防止内存泄漏。直接传递Blob对象通常更安全。

4. Base64字符串：vue-pdf不直接支持Base64字符串。你需要将其转换为Blob或ArrayBuffer。

   function base64ToBlob(base64, mimeType = ‘application/pdf‘) { const byteCharacters = atob(base64.split(‘,‘)[1]); // 去掉data:application/pdf;base64,前缀 const byteNumbers = new Array(byteCharacters.length); for (let i = 0; i < byteCharacters.length; i++) { byteNumbers[i] = byteCharacters.charCodeAt(i); } const byteArray = new Uint8Array(byteNumbers); return new Blob([byteArray], { type: mimeType }); } // 使用 const blob = base64ToBlob(yourBase64String); this.pdfSource = blob;

4.3 性能优化：处理大型PDF文件

当用户上传的PDF文件很大（比如超过50MB）时，直接一次性加载和渲染可能会导致页面卡顿、内存飙升，甚至浏览器标签页崩溃。我们需要一些优化策略。

策略一：分页加载与渲染vue-pdf本身是单页渲染的，这天然有利于分页加载。我们不需要一次性渲染所有页面。上面的组件已经实现了按页渲染。关键在于，当用户快速翻页时，可能会触发连续渲染，如果页面复杂，仍可能造成卡顿。可以加入简单的防抖逻辑，或者在非当前页的页面渲染完成后，暂停其他页面的预加载（这需要更复杂的控制）。

策略二：使用PDF.js的文本层和Canvas渲染vue-pdf默认使用Canvas渲染，这对于保证渲染保真度和性能是好的。但对于超大文件，可以尝试启用PDF.js的textLayer选项来优化文本选择体验，但这通常由vue-pdf内部处理。我们主要关注的是减少单次渲染的数据量。

策略三：后端配合与分片加载（高级）对于超大型PDF，最根本的优化是让后端支持范围请求（Range Request）。PDF.js支持加载PDF的特定字节范围。这意味着前端可以只请求当前需要渲染的页面的数据块，而不是整个文件。 这需要后端的支持，返回Accept-Ranges: bytes头，并正确处理Range请求头。前端配置vue-pdf的src时，需要传递一个包含url和range等参数的对象，或者使用PDF.js的更底层API。vue-pdf的:src支持传递一个配置对象：

this.pdfSource = { url: ‘https://api.example.com/huge-file.pdf‘, // 其他PDF.js文档加载选项，如withCredentials, httpHeaders等 // 对于分片，可能需要更复杂的逻辑，通常需要自定义PDF文档加载器 };

实现完整的分片加载比较复杂，可能涉及到修改vue-pdf使用的默认文档加载器。对于大多数应用（文件在100MB以内），一次性加载并利用vue-pdf的单页渲染特性，配合良好的加载提示，体验已经可以接受。如果真有超大文件需求，可能需要考虑直接使用PDF.js并实现自定义的PDFDataRangeTransport。

策略四：懒加载与虚拟滚动（多页并排查看时）如果你的需求是像书籍一样并排显示多页，那么渲染所有页面仍然是巨大的开销。此时可以考虑“虚拟滚动”技术：只渲染视口内及附近的页面，视口外的页面不渲染或销毁。这需要自己管理一个<pdf>组件数组，并根据滚动位置动态计算哪些page属性需要被赋值和渲染。这是一个相对高级的实现，会显著增加组件复杂度。

在我们的基础组件中，我们可以先实现一个简单的优化：在@page-loaded事件中，如果非当前页的页面加载完成，我们可以考虑降低其Canvas的显示精度或先隐藏，等用户滚动到附近时再恢复。但这属于更精细的优化范畴了。

5. 常见问题排查与实战技巧

即使按照文档一步步来，在实际开发中还是会遇到一些坑。这里我总结几个最常见的问题和解决方法。

5.1 跨域问题（CORS）

这是最高频的问题。当你使用远程URL作为PDF源时，浏览器会发起跨域请求。如果服务器没有返回正确的CORS响应头（如Access-Control-Allow-Origin: *或你的域名），控制台会报错：

Access to fetch at ‘https://other-domain.com/file.pdf‘ from origin ‘https://your-domain.com‘ has been blocked by CORS policy…

解决方案：

1. 后端配置：这是最根本的解决方案。让文件存储或代理服务器在响应中加上正确的CORS头。
2. 代理转发：在前端开发环境（如Vue CLI），可以配置vue.config.js中的devServer.proxy，将PDF请求代理到目标服务器，从而绕过浏览器的跨域限制。但这只适用于开发环境。

   // vue.config.js module.exports = { devServer: { proxy: { ‘/api/pdf‘: { target: ‘https://other-domain.com‘, changeOrigin: true, pathRewrite: { ‘^/api/pdf‘: ‘‘ }, }, }, }, };

   然后前端请求/api/pdf/actual-path.pdf。
3. Nginx反向代理：在生产环境，通过Nginx等Web服务器将PDF请求反向代理到目标地址，并在Nginx层面添加CORS头。

5.2 中文或其他语言文本显示为乱码

有时PDF里的中文显示出来是乱码或方框。这通常不是vue-pdf或前端的问题，而是PDF文件本身内嵌字体缺失导致的。解决方案：

1. 检查PDF源文件：用专业的PDF阅读器（如Adobe Acrobat）打开，看是否正常显示。如果不正常，问题出在生成PDF的环节，需要确保生成PDF时嵌入了所需的中文字体。
2. PDF.js的字体渲染：PDF.js会尝试用自带的字体包或系统字体来替代缺失的字体。对于复杂的中文字体，替代可能不完美。可以尝试在vue-pdf组件上设置:annotation=”false”，有时注释层会影响文本渲染。
3. 升级依赖：确保vue-pdf和底层的pdfjs-dist是最新版本，字体渲染可能在新版本中有改进。

5.3 页面渲染模糊或尺寸不对

这可能与CSS样式干扰或缩放计算有关。解决方案：

1. 检查容器CSS：确保包裹<pdf>组件的容器有明确的宽度，并且没有设置overflow: hidden（除非必要）而截断了内容。<pdf>组件渲染的Canvas会尽量适应容器宽度。
2. 理解scale和CSS transform：vue-pdf的:scale属性是作用于Canvas画布本身的缩放。如果你同时又用CSS的transform: scale()对容器进行了缩放，可能会产生叠加效果，导致模糊。尽量避免同时使用。
3. 高清屏适配：在高DPI（Retina）屏幕上，Canvas渲染可能会模糊。PDF.js内部会尝试处理，但有时需要确保Canvas的CSS尺寸和它的width/height属性匹配。vue-pdf组件通常能处理好，如果仍有问题，可以尝试监听@page-size事件，获取页面的原始尺寸，然后手动设置容器的尺寸。

5.4 内存泄漏问题

在单页面应用（SPA）中，如果频繁切换包含PDF预览的页面，或者PDF源是动态变化的，可能会发生内存泄漏。表现为浏览器内存占用持续上升，最终变卡。解决方案：

1. 及时销毁：在Vue组件的beforeDestroy或destroyed生命周期钩子中，如果使用了URL.createObjectURL()，务必调用URL.revokeObjectURL()释放内存。

   beforeDestroy() { if (this.objectUrl) { URL.revokeObjectURL(this.objectUrl); this.objectUrl = null; } // 此外，可以尝试强制清除pdf组件的内部引用 if (this.$refs.pdfRef) { this.$refs.pdfRef = null; } }

2. 使用Blob而非Object URL：如前所述，直接传递Blob对象给:src，让vue-pdf内部管理，通常比你自己管理Object URL更安全。
3. 复用组件时重置状态：当同一个PdfViewer组件用于显示不同的PDF时（通过:src变化），确保在watch: src的handler中彻底重置所有状态（如currentPage: 1,totalPages: 0），并清理旧的渲染。

5.5 与Vue 3的兼容性

原版的vue-pdf（npm i vue-pdf）主要针对Vue 2。如果你使用的是Vue 3，直接安装可能会遇到兼容性问题。解决方案：

1. 使用Vue 3兼容分支或替代库：社区有维护Vue 3版本的vue-pdf分支，例如@ckpack/vue-pdf。你可以尝试安装它：

   npm install @ckpack/vue-pdf

   其基本API与原版vue-pdf相似，但需要参考其特定文档。
2. 使用其他Vue 3 PDF库：例如pdfvuer的next版本可能支持Vue 3，或者寻找其他较新的库如vue3-pdfjs。选择时注意查看其GitHub仓库的活跃度和Issue情况。
3. 直接使用PDF.js与Vue 3组合：如果库的兼容性问题太多，对于Vue 3项目，可以考虑直接集成PDF.js，虽然工作量稍大，但控制力最强，没有兼容性包袱。可以将渲染逻辑封装成一个Composition API的usePdfhook。

6. 超越基础：高级功能与自定义扩展

基础预览功能满足后，我们可能会面临更复杂的需求。vue-pdf作为核心渲染器，结合一些额外的工作，可以实现不少高级功能。

6.1 实现缩略图导航

一个完整的PDF阅读器通常有侧边栏缩略图。我们可以利用vue-pdf渲染多个小尺寸的<pdf>组件来实现。 思路是：在@loaded事件获取总页数totalPages后，创建一个数组，例如thumbnailPages: [1, 2, 3, …, totalPages]。然后在模板中循环这个数组，为每一页创建一个缩小的<pdf>组件。

<template> <div class=”pdf-viewer-with-thumbnail”> <div class=”sidebar”> <div v-for=”pageNum in totalPages” :key=”pageNum” class=”thumbnail” :class=”{ active: pageNum === currentPage }” @click=”jumpToPage(pageNum)” > <pdf :src=”pdfSource” :page=”pageNum” :scale=”0.2″ // 缩小比例，例如20% ></pdf> <div class=”page-number”>{{ pageNum }}</div> </div> </div> <div class=”main-viewer”> <!-- 主预览区域，同上 --> <pdf :src=”pdfSource” :page=”currentPage” :scale=”scale”></pdf> </div> </div> </template>

性能注意：如果PDF页数很多（比如超过100页），同时渲染所有缩略图会非常消耗性能。需要做虚拟滚动：只渲染可视区域内的几十个缩略图。这需要计算滚动位置和每个缩略图的高度，动态更新thumbnailPages数组。

6.2 文本搜索与高亮

vue-pdf本身不提供文本搜索功能。但底层的PDF.js提供了强大的文本提取API。我们可以通过vue-pdf组件的引用，获取底层的PDF文档对象，然后使用PDF.js的API进行搜索。 基本步骤：

1. 获取pdf组件的实例，它有一个document属性（在@loaded事件触发后可用），指向PDF.js的PDF文档对象。
2. 调用document.getPage(pageNumber)获取页面对象。
3. 调用page.getTextContent()获取该页的文本内容及位置信息。
4. 在前端实现一个搜索算法，遍历所有页面的文本内容，匹配关键词。
5. 找到匹配项后，根据其位置信息（transform矩阵），在Canvas上对应位置绘制高亮矩形（这需要自己操作Canvas的2D上下文）。

这是一个相对复杂的功能，需要深入PDF.js的API。社区可能有基于vue-pdf的搜索插件，或者你可以考虑换用功能更集成的库如pdfvuer（它可能内置了搜索支持）。

6.3 打印与下载

打印和下载是常见需求。

• 下载：比较简单。如果PDF源是一个可直连的URL，直接提供一个<a>标签，设置href为该URL并添加download属性即可触发浏览器下载。如果源是Blob，可以通过URL.createObjectURL创建临时链接。

  downloadPdf() { const link = document.createElement(‘a‘); if (typeof this.pdfSource === ‘string‘) { link.href = this.pdfSource; } else if (this.pdfSource instanceof Blob) { const url = URL.createObjectURL(this.pdfSource); link.href = url; // 稍后需要 revokeObjectURL } link.download = ‘document.pdf‘; document.body.appendChild(link); link.click(); document.body.removeChild(link); }

• 打印：浏览器的window.print()会打印整个网页。要只打印PDF内容，一种方法是将当前页的PDF渲染到一个新的隐藏的iframe中，然后调用该iframe的contentWindow.print()。另一种更简单但效果可能不完美的方法是，利用@page-loaded事件，将渲染好的Canvas图片数据提取出来，放入一个专门用于打印的隐藏<div>，并应用打印样式（@media print），然后触发打印。

6.4 与Vue状态管理（如Vuex/Pinia）集成

在大型应用中，PDF预览的状态（如当前页码、缩放级别）可能需要跨组件共享或持久化。我们可以很容易地将PdfViewer组件的数据与Vuex或Pinia store绑定。 例如，定义一个store module：

// store/modules/pdfViewer.js (Vuex示例) export default { state: { currentPage: 1, totalPages: 0, scale: 1, rotate: 0, }, mutations: { SET_CURRENT_PAGE(state, page) { state.currentPage = page; }, SET_TOTAL_PAGES(state, pages) { state.totalPages = pages; }, SET_SCALE(state, scale) { state.scale = scale; }, SET_ROTATE(state, rotate) { state.rotate = rotate; }, }, actions: { // … 可以定义一些异步操作 }, };

然后在PdfViewer.vue组件中，将本地的data属性改为从store中map过来，并将方法中的commit操作改为提交mutation。这样，无论在哪里修改了store中的页码，所有引用了该状态的PDF预览器都会同步更新。这对于实现类似“阅读进度同步”的功能非常有用。

7. 替代方案浅析与总结

vue-pdf是一个优秀的工具，但它并非所有场景下的唯一选择。在项目技术选型时，了解其他选项的优缺点很重要。

1. pdfvuer：如前所述，它提供了更开箱即用的预览器组件，内置了工具栏、缩略图等。如果你需要快速搭建一个功能齐全的预览界面，且对UI定制要求不高，pdfvuer可能效率更高。它的API也更丰富，可能直接支持文本搜索等高级功能。

2. 直接使用PDF.js：当你的需求超出封装库的能力范围时（比如极其复杂的标注、表单填写、性能极限优化），直接使用PDF.js是最终方案。你需要自己管理worker、文档加载、页面渲染和事件交互。虽然初期成本高，但获得了最大的灵活性和控制力。Mozilla官方提供了丰富的示例。

3. 商用SDK或云服务：对于企业级应用，如果对PDF的功能要求极高（如在线编辑、数字签名、对比、高级渲染保真度），可以考虑商用SDK，如PSPDFKit、PDFTron等。它们提供了React/Vue/Angular的封装，功能强大，但价格昂贵。或者，将PDF渲染放到后端，前端只显示图片，这可以通过云服务或自建服务（如用pdf2image）实现，适合对安全有极高要求（防止源码下载）的场景，但牺牲了前端的文本选择和交互性。

回归到我们的项目，选择vue-pdf是基于这样一个判断：我们需要一个轻量、可控、能与Vue生态无缝集成的解决方案，用于处理常见的合同、协议预览需求，这些需求以“查看”为主，偶尔需要翻页、缩放和打印。vue-pdf完美地匹配了这个定位。

整个集成过程最深的体会是：理解底层原理（PDF.js）比单纯调用组件API更重要。当遇到跨域、字体、性能问题时，对PDF.js工作机制的了解能帮你快速定位方向。另外，对于前端资源的管理（如Object URL）一定要细心，SPA中的内存泄漏往往就源于这些细节。

最后，再分享一个小心得：在开发环境下，如果PDF文件很大，加载慢会影响调试效率。我通常会准备一个只有一两页的、体积小的测试PDF文件，放在本地public目录下，开发时先用它，等核心逻辑跑通后再换用真实的大文件进行性能测试。这能显著提升开发体验。