Vue项目PDF预览实战：基于vue-pdf的集成、优化与避坑指南

1. 项目概述：为什么前端要自己处理PDF预览？

在前后端分离的架构下，PDF文件的预览是一个高频且“微妙”的需求。很多新手可能会想，预览不就是后端返回一个文件链接，前端用个<a>标签打开或者用<iframe>嵌入就行了吗？理论上没错，但这在实际项目中会遇到一堆“坑”。比如，直接打开链接会跳转新页面或触发下载，破坏单页应用（SPA）的用户体验；用<iframe>嵌入，不同浏览器的兼容性和渲染效果参差不齐，尤其是对中文等字体的支持，经常出现乱码或布局错乱。更关键的是，你无法控制预览的UI，无法实现自定义的工具栏（如缩放、翻页、打印、搜索），也无法监听用户的交互行为（比如想知道用户翻到了第几页）。

所以，纯前端实现PDF预览的核心价值就出来了：将PDF文件的解析与渲染完全放在浏览器端完成，实现高度定制化、无缝集成的预览体验。这对于在线文档系统、电子合同签署、报告查看、电子书阅读等场景至关重要。Vue作为主流的前端框架，生态繁荣，其中vue-pdf就是一个专门为此而生的利器。它基于 Mozilla 的pdf.js，封装成了Vue组件，让我们能以声明式、组件化的方式轻松集成PDF预览功能。接下来，我就结合自己多次在项目中落地PDF预览的经验，从选型、集成、深度使用到避坑，给你拆解一遍。

2. 核心方案选型：vue-pdf的优劣与备选

面对PDF预览，前端开发者通常有几个选择：原生<iframe>、PDF.js原生集成、vue-pdf插件，以及一些商业库（如PSPDFKit）。这里我们重点分析vue-pdf。

2.1 为什么选择vue-pdf？

vue-pdf本质上是对PDF.js的Vue组件化封装。PDF.js是Mozilla开源的一个使用HTML5构建的PDF阅读器，它功能强大，但直接使用其API需要处理不少底层细节，比如Worker线程的加载、Canvas渲染管理、文档加载状态监听等。vue-pdf帮我们封装了这些复杂性，提供了如<pdf>这样的组件，让我们通过传递src属性就能渲染PDF，并通过事件和属性来控制外观和行为，极大地提升了开发效率。

它的主要优势在于：

1. 开箱即用：通过npm安装后，几行代码就能实现基础预览。
2. 组件化：完美契合Vue的生态，可以像使用普通组件一样管理PDF预览器的状态和生命周期。
3. 功能适中：提供了分页、缩放、旋转等核心功能，能满足大部分业务场景。
4. 基于PDF.js：背靠大树，兼容性和渲染质量有保障。

2.2 需要警惕的局限性

没有完美的方案，vue-pdf也有其明显的短板，这也是很多人在深入使用后吐槽的点：

1. 功能相对基础：它提供的是核心渲染能力。像文本选择、搜索、高级标注、表单填写等更复杂的功能，vue-pdf本身不支持，需要你基于它暴露的底层PDF.js实例去自行扩展，难度陡增。
2. 文档和社区支持：其官方文档比较简略，很多高级用法和问题解决需要去翻看源码或PDF.js的文档。
3. 性能与大型文件：对于上百页的超大PDF文件，一次性渲染所有页面可能会导致内存和CPU占用过高，页面卡顿。虽然vue-pdf支持page属性单页渲染，但实现流畅的分页加载逻辑需要自己动手。
4. 样式定制成本：想要一个与产品设计语言完全一致的预览器（比如自定义工具栏按钮的样式和布局），需要覆盖其内部组件的样式，可能会遇到CSS权重问题。

2.3 备选方案速览

• 直接使用PDF.js：如果你需要极致定制或用到vue-pdf不支持的高级功能，直接集成PDF.js是最终选择。它提供了最完整的API，但开发成本最高。
• 商业库（如PSPDFKit）：如果项目预算充足，且对功能（如协同批注、数字签名、高性能渲染）有企业级要求，商业库是省心省力的选择，它们通常提供React/Vue/Angular的SDK，文档和支持都非常完善。

注意：对于绝大多数中小型项目，需要快速实现一个美观、可控的PDF预览功能，vue-pdf依然是性价比最高的首选。我们的讨论也将围绕它展开。

3. 基础集成与快速上手

理论说完，我们直接动手。假设你有一个使用Vue CLI创建的Vue 2项目（vue-pdf主要支持Vue 2，对于Vue 3需要使用vue-pdf-embed或其他兼容库，原理相通）。

3.1 安装依赖

首先，通过npm或yarn安装vue-pdf。它依赖于pdfjs-dist，但通常会自动处理。

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

3.2 在组件中引入并使用

这里演示两种常用方式：全局注册和局部注册。

• 方式一：局部注册（推荐）在需要使用PDF预览的.vue组件中：

<template> <div class="pdf-preview-container"> <pdf :src="pdfUrl" @num-pages="pageCount = $event" @page-loaded="currentPage = $event"></pdf> <div class="controls"> <button @click="currentPage > 1 ? currentPage-- : 1">上一页</button> <span>{{ currentPage }} / {{ pageCount }}</span> <button @click="currentPage < pageCount ? currentPage++ : pageCount">下一页</button> </div> </div> </template> <script> // 1. 引入组件 import pdf from 'vue-pdf' export default { components: { pdf // 2. 局部注册 }, data() { return { pdfUrl: '/api/document/your-file.pdf', // 你的PDF文件地址，可以是相对路径、绝对URL或Blob URL pageCount: 0, // 总页数 currentPage: 1 // 当前页 } } } </script> <style scoped> .pdf-preview-container { border: 1px solid #eee; padding: 20px; } .controls { margin-top: 20px; text-align: center; } </style>

• 方式二：全局注册在main.js中：

import Vue from 'vue' import App from './App.vue' import pdf from 'vue-pdf' Vue.component('pdf', pdf) // 全局注册，所有组件都可以直接使用 <pdf> 标签 new Vue({ render: h => h(App), }).$mount('#app')

3.3 核心属性与事件解析

上面的例子已经用到了几个核心点：

• :src属性：这是最重要的属性，用于指定PDF源。它支持多种格式：
  • 字符串URL：指向PDF文件的路径。可以是相对路径、绝对路径或完整的HTTP URL。注意跨域问题！如果PDF文件在另一个域名下，需要确保该服务器返回了正确的CORS头。
  • Document-Object：PDF.js的文档对象，适用于更高级的编程式加载。
  • ArrayBuffer/Blob/Data URI：二进制数据或Base64编码的数据。这在处理文件上传预览时非常有用（后面会详细讲）。
• @num-pages事件：当PDF文档的元数据加载完毕，总页数确定后会触发此事件。回调参数就是总页数，我们用它来更新pageCount。
• @page-loaded事件：当某一页渲染完成时触发。回调参数是该页的页码。注意，这不是文档加载完成，而是每一页渲染都会触发。我们通常用它来更新当前页UI，但更精确的当前页监听可能需要结合其他逻辑。

仅仅这样，一个具备翻页功能的基础PDF预览器就完成了。但这只是开始，真实项目中的需求要复杂得多。

4. 深度功能实现与性能优化

基础预览只能算“能用”，离“好用”还差得远。下面我们深入几个关键场景。

4.1 处理文件上传实时预览

这是一个非常常见的需求：用户选择本地PDF文件后，不等待上传至服务器，直接在页面内预览。

<template> <div> <input type="file" accept="application/pdf" @change="onFileChange" /> <div v-if="pdfSrc"> <pdf :src="pdfSrc" :page="currentPage"></pdf> </div> </div> </template> <script> import pdf from 'vue-pdf' export default { components: { pdf }, data() { return { pdfSrc: null, currentPage: 1 } }, methods: { onFileChange(event) { const file = event.target.files[0] if (file && file.type === 'application/pdf') { // 关键步骤：将File对象转换为URL对象 this.pdfSrc = URL.createObjectURL(file) // 重要：在组件销毁或预览新文件前，记得释放之前创建的URL对象，避免内存泄漏 // if (this.pdfSrc) { // URL.revokeObjectURL(this.pdfSrc) // } } else { alert('请选择PDF文件') this.pdfSrc = null } } }, beforeDestroy() { // 组件销毁时清理URL对象 if (this.pdfSrc) { URL.revokeObjectURL(this.pdfSrc) } } } </script>

实操心得：使用URL.createObjectURL是前端预览本地文件的标准做法，它创建一个指向内存中文件对象的临时URL，性能比FileReader.readAsDataURL（转Base64）要好，尤其是大文件。但务必记住在合适的时机（如组件销毁、切换文件时）调用URL.revokeObjectURL来释放内存，这是一个容易被忽略的内存泄漏点。

4.2 实现分页加载与缩放控制

一次性渲染所有页面（使用v-for循环多个<pdf>组件，每个绑定不同的:page）在页面较多时会导致严重性能问题。正确的做法是只渲染当前视口附近的页面。

<template> <div ref="container" class="pdf-viewport" @scroll="onScroll"> <div class="pdf-pages" :style="{ height: totalHeight + 'px' }"> <div v-for="pageNum in visiblePages" :key="pageNum" class="pdf-page-container" :style="{ top: getPageTop(pageNum) + 'px' }" > <pdf :src="pdfUrl" :page="pageNum" :scale="scale" @page-loaded="onPageLoaded(pageNum, $event)" ></pdf> </div> </div> </div> <div class="toolbar"> <button @click="scale -= 0.1">-</button> <span>缩放: {{ (scale * 100).toFixed(0) }}%</span> <button @click="scale += 0.1">+</button> </div> </template> <script> import pdf from 'vue-pdf' export default { components: { pdf }, data() { return { pdfUrl: '', totalPages: 0, currentPage: 1, scale: 1.0, pageHeights: {}, // 记录每页渲染后的实际高度 visibleWindow: { start: 1, end: 5 }, // 当前视口可见的页码范围 pageGap: 20 // 页面间距 } }, computed: { totalHeight() { // 计算所有页面的总高度（用于容器滚动） let height = 0 for (let i = 1; i <= this.totalPages; i++) { height += (this.pageHeights[i] || 800) + this.pageGap // 默认高度800px } return height }, visiblePages() { // 计算当前需要渲染的页码数组 const pages = [] for (let i = this.visibleWindow.start; i <= this.visibleWindow.end; i++) { if (i >= 1 && i <= this.totalPages) pages.push(i) } return pages } }, mounted() { this.loadDocument() }, methods: { async loadDocument() { // 这里可以加载PDF并获取总页数，假设通过事件获取 // 实际中，可能需要先创建一个`pdf.createLoadingTask(src)`来获取文档对象 const loadingTask = pdf.createLoadingTask(this.pdfUrl) const pdfDocument = await loadingTask.promise this.totalPages = pdfDocument.numPages // 初始化可视窗口 this.visibleWindow.end = Math.min(5, this.totalPages) }, onScroll() { // 计算滚动位置，更新visibleWindow.start和end // 这是一个简化的示例，实际计算需要根据每个页面的精确高度和滚动位置进行 const scrollTop = this.$refs.container.scrollTop let accumulatedHeight = 0 let newStart = 1 for (let i = 1; i <= this.totalPages; i++) { const pageHeight = this.pageHeights[i] || 800 if (accumulatedHeight + pageHeight > scrollTop) { newStart = Math.max(1, i - 2) // 提前2页加载 break } accumulatedHeight += pageHeight + this.pageGap } this.visibleWindow.start = newStart this.visibleWindow.end = Math.min(newStart + 4, this.totalPages) // 可视窗口大小为5页 }, onPageLoaded(pageNum, event) { // 记录该页的实际渲染高度 // 注意：`vue-pdf`组件渲染出的canvas或div高度需要获取 // 这里假设通过$refs或事件对象能拿到，实际可能需要用`setTimeout`等待DOM更新后获取 // this.$nextTick(() => { ... 获取高度 ... }) // this.pageHeights[pageNum] = height }, getPageTop(pageNum) { // 计算某一页在滚动容器中的top位置 let top = 0 for (let i = 1; i < pageNum; i++) { top += (this.pageHeights[i] || 800) + this.pageGap } return top } } } </script> <style scoped> .pdf-viewport { height: 80vh; overflow-y: auto; border: 1px solid #ccc; position: relative; } .pdf-pages { position: relative; } .pdf-page-container { position: absolute; width: 100%; margin-bottom: 20px; } .toolbar { margin-top: 10px; } </style>

这个示例展示了虚拟列表的思想在PDF预览中的应用核心：只渲染用户看得见或即将看得见的页面。虽然vue-pdf没有内置此功能，但我们可以通过监听滚动、计算位置、动态渲染<pdf>组件来实现，这对提升超长文档的体验至关重要。同时，我们通过:scale属性绑定了缩放比例，实现了缩放控制。

4.3 自定义工具栏与事件交互

一个产品级的预览器需要美观易用的工具栏。我们可以完全自己实现一个工具栏组件，并与vue-pdf组件联动。

<template> <div class="custom-pdf-viewer"> <!-- 自定义工具栏 --> <div class="toolbar"> <button @click="zoomOut" :disabled="scale <= 0.2">-</button> <select v-model="scale"> <option value="0.5">50%</option> <option value="0.75">75%</option> <option value="1">100%</option> <option value="1.25">125%</option> <option value="1.5">150%</option> <option value="2">200%</option> </select> <button @click="zoomIn" :disabled="scale >= 3">+</button> <button @click="rotateLeft">↺</button> <button @click="rotateRight">↻</button> <button @click="print" v-if="supportsPrint">打印</button> <button @click="download">下载</button> <span class="page-info">{{ currentPage }} / {{ pageCount }}</span> <input type="number" v-model.number="jumpPage" min="1" :max="pageCount" @keyup.enter="goToPage" /> <button @click="goToPage">跳转</button> </div> <!-- PDF渲染区域 --> <div class="pdf-render-area" @click="handleCanvasClick"> <pdf ref="pdfViewer" :src="pdfSrc" :page="currentPage" :scale="scale" :rotate="rotation" @num-pages="pageCount = $event" @page-loaded="onPageLoaded" @link-clicked="onLinkClicked" ></pdf> </div> </div> </template> <script> import pdf from 'vue-pdf' export default { components: { pdf }, props: ['fileUrl'], data() { return { pdfSrc: this.fileUrl, currentPage: 1, pageCount: 0, scale: 1, rotation: 0, jumpPage: 1, supportsPrint: !!window.print } }, watch: { fileUrl(newVal) { this.pdfSrc = newVal this.currentPage = 1 // 重置到第一页 } }, methods: { zoomOut() { this.scale = Math.max(0.2, this.scale - 0.1) }, zoomIn() { this.scale = Math.min(3, this.scale + 0.1) }, rotateLeft() { this.rotation -= 90 }, rotateRight() { this.rotation += 90 }, goToPage() { const page = parseInt(this.jumpPage) if (page >= 1 && page <= this.pageCount) { this.currentPage = page this.jumpPage = page } }, onPageLoaded(pageNum) { // 可以在这里更新一些状态，比如高亮当前页的缩略图 console.log(`第 ${pageNum} 页加载完成`) }, onLinkClicked(link) { // 处理PDF内部的链接点击 // link 对象包含链接信息，可能是跳转到PDF内另一页，也可能是外部URL if (link.startsWith('http')) { window.open(link, '_blank') } else { // 可能是页码，例如 `#page=5` const match = link.match(/#page=(\d+)/) if (match) { this.currentPage = parseInt(match[1]) } } }, handleCanvasClick(event) { // 示例：点击画布某处，可以做一些交互，比如添加批注点 const rect = event.target.getBoundingClientRect() const x = event.clientX - rect.left const y = event.clientY - rect.top console.log(`点击位置相对于Canvas: (${x}, ${y})`) // 这里可以触发一个自定义事件，让父组件处理批注逻辑 this.$emit('canvas-clicked', { page: this.currentPage, x, y }) }, print() { window.print() // 浏览器原生打印，会打印整个页面。对于只打印PDF区域，需要更复杂的处理。 }, download() { // 触发文件下载 const a = document.createElement('a') a.href = this.pdfSrc a.download = 'document.pdf' // 可以设置一个动态文件名 document.body.appendChild(a) a.click() document.body.removeChild(a) } } } </script> <style scoped> .custom-pdf-viewer { border: 1px solid #ddd; border-radius: 4px; overflow: hidden; } .toolbar { background-color: #f5f5f5; padding: 10px; display: flex; align-items: center; gap: 10px; border-bottom: 1px solid #ddd; } .toolbar button, .toolbar select { padding: 5px 10px; border: 1px solid #ccc; border-radius: 3px; background: white; cursor: pointer; } .toolbar button:disabled { opacity: 0.5; cursor: not-allowed; } .page-info { margin-left: auto; margin-right: 10px; } .pdf-render-area { padding: 20px; text-align: center; min-height: 500px; display: flex; justify-content: center; align-items: flex-start; background-color: #fafafa; } </style>

这个自定义组件展示了如何围绕vue-pdf构建一个功能完整的预览器。我们通过:scale和:rotate属性控制了显示，通过@link-clicked事件处理了PDF内部链接，甚至通过监听Canvas点击事件为未来添加批注功能留下了接口。工具栏的样式和布局可以完全自定义，与你的产品设计保持一致。

5. 常见问题、疑难杂症与排查实录

在实际开发中，你一定会遇到各种各样的问题。下面是我踩过的一些坑和解决方案。

5.1 跨域问题（CORS）

这是最常见的问题。如果你的PDF文件存放在另一个域名下（比如CDN或独立的文件服务器），浏览器会因为同源策略阻止PDF.js加载该文件。

• 现象：PDF区域空白，浏览器控制台报错：Failed to load PDF.或NetworkError。
• 解决方案：
  1. 后端配置CORS：这是根本解决方法。确保提供PDF文件的服务端在响应头中设置了正确的Access-Control-Allow-Origin。例如：Access-Control-Allow-Origin: *或Access-Control-Allow-Origin: https://your-frontend-domain.com。
  2. 代理请求：如果无法修改文件服务器配置，可以让自己的后端服务器去请求PDF文件，然后前端从自己的后端服务器获取。这样对于前端来说就是同源请求了。
  3. 使用withCredentials：如果PDF服务需要认证（如Cookies），在创建vue-pdf的src时，可能需要传递一个配置对象，设置withCredentials。但vue-pdf的:src直接传字符串URL时不支持。这时需要使用pdf.createLoadingTask方法。

// 使用createLoadingTask处理带认证的请求 import pdf from 'vue-pdf' export default { data() { return { pdfTask: null } }, mounted() { this.loadPdfWithAuth() }, methods: { async loadPdfWithAuth() { // 创建一个加载任务，可以传入配置 this.pdfTask = pdf.createLoadingTask({ url: 'https://other-domain.com/file.pdf', withCredentials: true // 发送凭据（如Cookies） // 还可以设置其他httpHeaders }) // 将返回的promise赋值给src this.pdfSrc = this.pdfTask try { const pdfDoc = await this.pdfTask.promise console.log('PDF加载成功，总页数：', pdfDoc.numPages) } catch (error) { console.error('PDF加载失败：', error) } } } }

5.2 中文或其他字体显示乱码/空白

• 现象：PDF中的文字没有显示出来，或者显示为乱码。
• 原因：PDF.js（以及vue-pdf）依赖于浏览器环境来渲染文本。如果PDF文件内嵌了非常用字体，或者使用了特殊的字体编码，而浏览器没有对应的字体资源，就可能渲染失败。
• 解决方案：
  1. 检查PDF源文件：最可靠的PDF预览是那些内嵌了所有所需字体子集的PDF。可以尝试用专业的PDF编辑器（如Adobe Acrobat）检查字体嵌入情况。
  2. 使用PDF.js的字体渲染模式：PDF.js默认会尝试用Canvas绘制文本，如果失败会回退到图像。但有时需要强制其使用“原生”Canvas文本渲染，这可以通过修改PDF.js的CMap参数来改善对复杂字体的支持。不过vue-pdf对此的暴露接口有限。一个更直接的方法是引入pdfjs-dist的字体包。
  3. 引入CMap资源（高级）：

     npm install pdfjs-dist

     然后在项目中引入：

     import * as pdfjsLib from 'pdfjs-dist/build/pdf' import pdfjsWorker from 'pdfjs-dist/build/pdf.worker.entry' pdfjsLib.GlobalWorkerOptions.workerSrc = pdfjsWorker // 设置CMap参数，指向cmap资源 const loadingTask = pdfjsLib.getDocument({ url: pdfUrl, cMapUrl: 'https://unpkg.com/pdfjs-dist@2.16.105/cmaps/', cMapPacked: true, }) // 然后将loadingTask传递给vue-pdf（这需要更底层的集成，可能不如直接使用PDF.js方便）

     对于vue-pdf，更简单的尝试是确保你的构建过程能正确引入pdfjs-dist的worker。字体问题通常比较棘手，如果预览需求对字体保真度要求极高，可能需要考虑后端渲染为图片再返回给前端。

5.3 性能问题：渲染慢、内存占用高

• 现象：加载几十页的PDF时，页面卡顿、滚动不流畅，甚至浏览器标签页内存占用飙升。
• 解决方案：
  1. 实施虚拟列表/分页加载：如前文4.2节所述，这是解决性能问题的核心。永远不要一次性渲染所有页面。
  2. 降低默认分辨率：vue-pdf的:scale属性默认是1.0（100%）。对于快速浏览，可以初始设置为0.8或0.5，用户需要看清细节时再放大。更低的缩放比例意味着更小的Canvas绘制面积，渲染更快。
  3. 及时销毁组件：在Vue组件beforeDestroy钩子中，如果使用了URL.createObjectURL，务必调用URL.revokeObjectURL。如果使用了pdf.createLoadingTask，可以考虑调用其destroy()方法（如果提供）来清理资源。
  4. 使用Web Worker：确保PDF.js的Worker在正确工作。Worker会将PDF解析工作放在后台线程，避免阻塞主线程。vue-pdf默认会尝试从CDN加载Worker，如果网络受限可能导致回退到主线程解析，性能变差。可以手动指定Worker路径：

     // 在入口文件（如main.js） import pdf from 'vue-pdf' import workerSrc from 'pdfjs-dist/build/pdf.worker.entry' pdf.pdfjsWorker = workerSrc

5.4 在Vue 3中使用

vue-pdf主要针对Vue 2。如果你使用的是Vue 3，官方仓库可能不兼容。社区有替代方案：

1. vue-pdf-embed：这是一个专为Vue 3设计的轻量级PDF预览组件，API更现代。

   npm install vue-pdf-embed

   <template> <VuePdfEmbed :source="pdfSource" /> </template> <script setup> import { ref } from 'vue' import VuePdfEmbed from 'vue-pdf-embed' const pdfSource = ref('/api/file.pdf') </script>

2. 直接使用PDF.js：在Vue 3的组合式API中集成PDF.js反而可能更清晰灵活。

5.5 其他实用技巧与问题

• 获取PDF元信息（如标题、作者）：vue-pdf通过@num-pages事件提供了页数。要获取更多元数据，需要用到pdf.createLoadingTask返回的文档对象。

  const loadingTask = pdf.createLoadingTask(src) loadingTask.promise.then(pdfDoc => { pdfDoc.getMetadata().then(metadata => { console.log('标题:', metadata.info.Title) console.log('作者:', metadata.info.Author) }) }) this.pdfSrc = loadingTask // 仍然可以赋值给src

• 处理密码保护的PDF：PDF.js支持打开有密码的PDF。你需要监听文档加载的错误，如果错误是密码错误，则提示用户输入密码，然后重新用密码加载。

  const loadingTask = pdf.createLoadingTask({ url: pdfUrl, password: 'user-provided-password' // 首次尝试的密码，可以为空 }) loadingTask.promise.then( pdfDoc => { /* 成功 */ }, error => { if (error.name === 'PasswordException') { // 弹出对话框让用户输入密码 const userPassword = prompt('该PDF受密码保护，请输入密码：') if (userPassword) { // 用新密码重新创建加载任务 this.loadWithPassword(userPassword) } } } )

• 自定义渲染错误提示：当PDF加载或渲染失败时，vue-pdf组件内部可能会显示一个错误信息。你可以通过CSS覆盖它，或者通过监听错误事件来完全自定义UI。

  <pdf :src="src" @error="onPdfError"></pdf> ... methods: { onPdfError(error) { console.error('PDF渲染错误:', error) this.errorMessage = '无法加载PDF文档，请检查文件是否损坏或链接是否正确。' // 显示一个友好的错误提示组件 } }

6. 项目实战：构建一个完整的PDF预览组件

结合以上所有知识点，我们可以规划一个用于生产环境的、健壮的PDF预览组件。它应该具备以下特性：

1. 属性接口清晰：

   • src: 支持URL、Blob、ArrayBuffer等多种格式。
   • page: 控制当前显示页（单页模式）。
   • scale: 缩放比例。
   • rotate: 旋转角度。
   • show-toolbar: 是否显示默认工具栏。
   • watermark: 可选水印文本。

2. 事件丰富：

   • loaded: 文档加载完成。
   • page-change: 当前页变化。
   • zoom-change: 缩放比例变化。
   • error: 加载或渲染错误。

3. 插槽支持：

   • toolbar-left/toolbar-right: 允许用户自定义工具栏左右区域的内容。
   • loading: 自定义加载状态UI。
   • error: 自定义错误状态UI。

4. 内部实现优化：

   • 使用虚拟列表技术进行分页渲染。
   • 集成Web Worker并正确配置路径。
   • 实现图片、Blob URL等资源的自动清理。
   • 对移动端触控手势（双指缩放、滑动翻页）提供基本支持。

由于篇幅限制，这里无法贴出完整代码，但你可以基于前面章节的示例，按照这个设计思路去封装。核心是将vue-pdf作为底层的渲染引擎，在其之上构建一层符合你业务逻辑和设计规范的UI和状态管理层。

最后，我想分享一点个人体会：前端PDF预览看起来是个小功能，但真想做好、做稳定，需要考虑的细节非常多，从网络请求、二进制数据处理、Canvas渲染性能，到UI交互、状态管理、错误边界，几乎涵盖了前端开发的多个方面。vue-pdf是一个优秀的起点，但它更像是一把“瑞士军刀”的基础刀片，要打造称手的工具，还需要你根据实际场景去打磨它的手柄（UI）和附加功能。遇到问题时，多查查PDF.js的官方文档和Issue，很多底层问题的答案都在那里。希望这篇长文能帮你少走些弯路，顺利搞定Vue项目中的PDF预览需求。