如何在 Vue 项目中轻松嵌入 PDF？vue-pdf-embed 完整使用指南

vue-pdf-embed 是一款专为 Vue 2 和 Vue 3 设计的 PDF 嵌入组件，让开发者能够快速在 Vue 应用中集成 PDF 文档展示功能，支持 URL、Base64、二进制数据等多种 PDF 来源格式，提升项目文档展示体验。

📚 项目核心技术解析

Vue.js 框架支持

作为基于 Vue 生态的组件，vue-pdf-embed 深度适配 Vue 3 的 Composition API，同时保留对 Vue 2 的兼容性，通过 src/index.ts 和 src/index.essential.ts 实现不同版本的入口适配，满足各类 Vue 项目需求。

PDF.js 渲染引擎

组件底层采用 Mozilla 开发的 PDF.js 库处理 PDF 渲染逻辑，通过 src/composables.ts 中的钩子函数管理 PDF 加载、渲染状态，确保跨浏览器兼容性和渲染质量。

🚀 三步快速安装流程

1. 环境准备

确保已安装 Node.js 和 npm/yarn，通过 Vue CLI 创建或使用现有 Vue 项目：

# 检查 Node 版本
node -v
# 检查 npm 版本
npm -v

2. 安装组件

在项目根目录执行以下命令安装 vue-pdf-embed：

# 使用 npm
npm install vue-pdf-embed

# 或使用 yarn
yarn add vue-pdf-embed

3. 基础使用示例

在 Vue 单文件组件中引入并使用：

<template>
  <div class="pdf-container">
    <VuePdfEmbed :source="pdfUrl" />
  </div>
</template>

<script setup>
import VuePdfEmbed from 'vue-pdf-embed'

// PDF 文档地址
const pdfUrl = '/static/sample.pdf'
</script>

<style scoped>
.pdf-container {
  width: 100%;
  max-width: 800px;
  margin: 20px auto;
}
</style>

⚙️ 高级配置与优化

多来源支持配置

组件支持多种 PDF 来源格式，通过 source 属性灵活配置：

<template>
  <VuePdfEmbed 
    :source="pdfSource" 
    @loaded="onPdfLoaded"
    @error="onPdfError"
  />
</template>

<script setup>
import { ref } from 'vue'
import VuePdfEmbed from 'vue-pdf-embed'

// URL 来源
const pdfSource = ref('https://example.com/document.pdf')

// Base64 来源示例
// pdfSource.value = 'data:application/pdf;base64,JVBERi0xLjQK...'

const onPdfLoaded = () => {
  console.log('PDF 加载完成')
}

const onPdfError = (error) => {
  console.error('PDF 加载失败:', error)
}
</script>

资源路径配置

当遇到字体或图片渲染问题时，可通过配置资源路径解决：

<VuePdfEmbed
  :source="{
    url: '/docs/report.pdf',
    cMapUrl: '/assets/pdfjs/cmaps/'
  }"
  image-resources-path="/assets/pdfjs/images/"
/>

建议将 PDF.js 资源文件放置在项目 public 目录下，通过相对路径引用。

样式自定义

通过引入组件样式文件并覆盖变量实现自定义样式：

/* 引入默认样式 */
@import 'vue-pdf-embed/dist/styles/annotationLayer.css';
@import 'vue-pdf-embed/dist/styles/textLayer.css';

/* 自定义文本层样式 */
.textLayer {
  font-family: 'Microsoft YaHei', sans-serif;
}

/* 自定义注释层样式 */
.annotationLayer {
  opacity: 0.8;
}

🧪 功能测试与问题排查

本地开发测试

使用项目提供的开发环境进行功能验证：

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/vu/vue-pdf-embed.git
# 安装依赖
cd vue-pdf-embed && npm install
# 启动开发服务器
npm run dev

访问 http://localhost:3000 查看 dev/App.vue 中的示例效果。

常见问题解决

• 跨域问题：确保 PDF 资源服务器配置 CORS 或使用代理
• 大型 PDF 加载缓慢：通过 page 属性实现分页加载
• 移动端适配：添加 meta 标签并使用相对单位设置容器宽度

📝 使用注意事项

• 对于需要频繁切换 PDF 的场景，建议使用 v-if 控制组件卸载以释放内存
• 密码保护的 PDF 文件需通过 source.password 配置密码
• 生产环境建议使用 CDN 引入 PDF.js 资源，减少打包体积

通过以上步骤，你可以轻松在 Vue 项目中集成专业的 PDF 展示功能。组件源码位于 src/VuePdfEmbed.vue，更多高级用法可参考项目测试文件 test/VuePdfEmbed.test.ts 中的测试用例。