Vue3 PDF 预览不用愁!vue-pdf-preview 极简实战,全端适配一步到位-夜雨聆风

Vue3 PDF 预览不用愁!vue-pdf-preview 极简实战,全端适配一步到位

做 Vue3 开发，PDF 预览绝对是高频刚需 —— 后台合同查看、H5 文档展示、移动端报表预览，几乎处处都要用。

但原生 pdfjs-dist 配置繁琐、跨域难处理、移动端适配拉胯、自定义功能麻烦？今天给大家安利一款Vue3 专属 PDF 预览神器：vue-pdf-preview，基于 pdfjs-dist 深度封装，零门槛上手，几行代码实现专业级预览效果！

🚀 组件核心亮点

vue-pdf-preview 是为 Vue3 量身打造的轻量预览组件，完美适配组合式 API 与 TypeScript，自带这些实用能力：

开箱即用：渲染、翻页、缩放、旋转、下载、打印一键集成
全端自适应：PC 端优雅展示，移动端自动适配屏幕
高度自定义：可隐藏工具栏、添加水印、控制初始缩放
性能友好：按需加载，轻量化不臃肿
兜底完善：支持加载状态、错误回调，业务更稳

不用纠结底层解析逻辑，专注业务即可。

📦 第一步：环境安装（30 秒搞定）

项目需为 Vue3 + Vite/Webpack 环境，执行安装命令（pdfjs-dist 为核心依赖，必须同步安装，建议 3.x+ 版本）：

# npm
npm install vue-pdf-preview pdfjs-dist --save

# yarn
yarn add vue-pdf-preview pdfjs-dist

# pnpm（推荐）
pnpm add vue-pdf-preview pdfjs-dist

全局注册（多页面复用首选）

在 main.ts 中全局注册，项目内任意组件可直接使用：

// main.ts
import { createApp } from'vue'
import App from'./App.vue'
import VuePdfPreview from'vue-pdf-preview'
// 引入组件样式
import'vue-pdf-preview/lib/style.css'

const app = createApp(App)
app.use(VuePdfPreview)
app.mount('#app')

📄 第二步：基础实战（最简可用版）

全局注册后，仅需几行核心代码，即可实现 PDF 预览 + 分页控制，直接复制可用：

<!-- PdfPreviewDemo.vue -->
<template>
<divclass="pdf-preview-container">
<!-- 核心预览组件 -->
<vue-pdf-preview
:pdf-url="pdfUrl"
:page="currentPage"
      @page-change="handlePageChange"
    />

<!-- 自定义分页控制 -->
<divclass="pdf-controls">
<button @click="currentPage--":disabled="currentPage <= 1">上一页</button>
<span>{{ currentPage }} / {{ totalPages }}</span>
<button @click="currentPage++":disabled="currentPage >= totalPages">下一页</button>
</div>
</div>
</template>

<scriptsetuplang="ts">
import { ref } from'vue'

// PDF 地址（支持本地路径/远程 URL，远程需处理跨域）
const pdfUrl = ref('https://xxxx.com/static/test.pdf')
// 当前页码
const currentPage = ref(1)
// 总页数
const totalPages = ref(0)

// 页码切换回调
const handlePageChange = (page: number, pages: number) => {
  currentPage.value = page
  totalPages.value = pages
}
</script>

<stylescoped>
.pdf-preview-container {
width: 100%;
max-width: 800px;
margin: 20px auto;
}
.pdf-controls {
display: flex;
align-items: center;
justify-content: center;
gap: 16px;
margin-top: 16px;
}
.pdf-controlsbutton {
padding: 8px16px;
border: none;
background: #409eff;
color: #fff;
border-radius: 4px;
cursor: pointer;
}
.pdf-controlsbutton:disabled {
background: #ccc;
cursor: not-allowed;
}
</style>

⚙️ 第三步：进阶功能（业务必备）

1. 自定义工具栏（按需显隐功能）

不想暴露下载、打印？通过 toolbar-config 精准控制：

<vue-pdf-preview
:pdf-url="pdfUrl"
:toolbar-config="toolbarConfig"
/>

<scriptsetup>
import { ref } from'vue'
const toolbarConfig = ref({
zoom: true,      // 开启缩放
rotate: true,    // 开启旋转
download: false, // 隐藏下载
print: false,    // 隐藏打印
page: true// 显示页码
})
</script>

2. 移动端适配 + 文档水印

内部文件加水印防转发，同时自动适配手机屏幕：

<vue-pdf-preview
:pdf-url="pdfUrl"
:watermark-text="'内部文档-禁止转发'"
:mobile-adaptive="true"
:scale="1.2"  <!-- 初始缩放比例 -->
/>

3. 加载状态 + 错误兜底

提升用户体验，避免白屏 / 无提示报错：

<template>
<vue-pdf-preview
:pdf-url="pdfUrl"
    @loading="handleLoading"
    @error="handleError"
  />
<divv-if="isLoading"class="loading-tip">PDF 加载中...</div>
<divv-if="hasError"class="error-tip">加载失败：{{ errorMsg }}</div>
</template>

<scriptsetup>
import { ref } from'vue'
const isLoading = ref(false)
const hasError = ref(false)
const errorMsg = ref('')

// 加载状态回调
const handleLoading = (status: boolean) => {
  isLoading.value = status
}
// 错误回调
const handleError = (err: Error) => {
  hasError.value = true
  errorMsg.value = err.message
console.error('PDF 加载失败', err)
}
</script>

⚠️ 开发避坑指南（必看）

跨域问题远程 PDF 需后端配置 CORS，或前端配置代理（vite.config.ts/vue.config.js），否则无法加载。
本地 PDF 路径本地文件建议放入 public 目录，直接用 /xxx.pdf 访问，避免路径报错。
大文件优化超大 PDF 建议后端支持分片加载，配合组件加载提示，避免长时间白屏。
版本兼容pdfjs-dist 优先选 3.x+，避免与 Vue3 出现兼容问题。

✅ 总结

vue-pdf-preview 是 Vue3 生态里轻量、易用、稳定的 PDF 预览方案：

基础场景：仅配 pdf-url 即可快速预览
复杂场景：支持水印、自定义工具栏、全端适配
开发效率：省去底层配置，大幅缩短开发时间

不管是后台管理、H5 还是移动端项目，都能轻松搞定 PDF 预览需求。