uniapp中使用pdf.js实现H5端PDF预览功能

1. 项目概述

在Web开发中，PDF文件预览是一个常见的需求场景。无论是企业文档管理系统、在线教育平台还是电子合同签署系统，都需要为用户提供便捷的PDF预览功能。传统的解决方案通常有以下几种：

1. 直接使用浏览器内置的PDF查看器
2. 通过iframe嵌入第三方服务
3. 使用专业的JavaScript库进行渲染

每种方案都有其优缺点。第一种虽然简单，但存在浏览器兼容性问题；第二种依赖外部服务，可能涉及隐私和安全问题；第三种则需要一定的技术实现成本。本文将重点介绍如何在uniapp框架下，通过pdf.js实现稳定可靠的H5端PDF预览功能。

2. 技术选型与准备

2.1 为什么选择pdf.js

pdf.js是Mozilla开发的一个开源JavaScript库，它可以在不依赖任何插件的情况下，在浏览器中渲染PDF文档。相比其他方案，pdf.js具有以下优势：

• 完全开源免费：由Mozilla维护，社区活跃度高
• 跨平台兼容：支持所有现代浏览器
• 功能丰富：提供文本选择、缩放、搜索等完整功能
• 可定制性强：可以根据需求修改UI和功能

2.2 环境准备

在开始之前，请确保你的开发环境满足以下要求：

1. 已安装Node.js（建议版本14+）
2. 已创建uniapp项目（基于Vue3）
3. 项目支持H5平台（需要在manifest.json中配置）

3. 核心实现步骤

3.1 下载并配置pdf.js

首先我们需要获取pdf.js的预构建版本：

1. 访问pdf.js官网的下载页面：https://mozilla.github.io/pdf.js/getting_started/#download
2. 下载"Stable (prebuilt)"版本的压缩包
3. 解压后，在项目的static目录下创建pdfjs文件夹
4. 将解压得到的build和web文件夹复制到static/pdfjs目录

最终目录结构应如下所示：

code复制/static
└─ /pdfjs
   ├─ /build
   │  ├─ pdf.js
   │  └─ pdf.worker.js
   └─ /web
      ├─ viewer.html
      ├─ viewer.css
      └─ ...

注意：请确保复制的是完整文件夹，不要遗漏任何文件，特别是pdf.worker.js这个文件，它是pdf.js的多线程处理核心。

3.2 创建PDF预览组件

在uniapp项目中创建一个新的页面组件：

1. 在pages目录下新建pdf-preview文件夹
2. 创建pdf-preview.vue文件
3. 复制以下代码：

html复制<template>
  <view class="pdf-preview-container">
    <web-view :src="pdfUrl"></web-view>
  </view>
</template>

<script setup>
import { ref } from 'vue';
import { onLoad } from '@dcloudio/uni-app';

const pdfUrl = ref('');

// 测试用的PDF文件
const samplePdf = 'https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf';

onLoad((options) => {
  const type = options.type || '2'; // 默认使用pdf.js
  const urlToPreview = options.url ? decodeURIComponent(options.url) : samplePdf;

  if (type === '1') {
    // 方法一：直接使用web-view加载PDF
    pdfUrl.value = urlToPreview;
  } else {
    // 方法二：使用pdf.js预览（推荐）
    // #ifdef H5
    pdfUrl.value = `/static/pdfjs/web/viewer.html?file=${encodeURIComponent(urlToPreview)}`;
    // #endif
    
    // #ifndef H5
    uni.showToast({ title: '此功能仅支持Web端', icon: 'none' });
    // #endif
  }

  uni.setNavigationBarTitle({
    title: 'PDF预览'
  });
});
</script>

<style>
.pdf-preview-container {
  width: 100%;
  height: 100%;
}
</style>

3.3 注册页面路由

在pages.json中添加新页面的路由配置：

json复制{
  "path": "pages/pdf-preview/pdf-preview",
  "style": {
    "navigationBarTitleText": "PDF预览"
  }
}

4. 功能使用与调用

4.1 基本调用方式

在其他页面中，可以通过以下方式调用PDF预览功能：

javascript复制// 使用pdf.js预览（推荐）
const pdfUrl = 'https://example.com/document.pdf';
uni.navigateTo({
  url: `/pages/pdf-preview/pdf-preview?type=2&url=${encodeURIComponent(pdfUrl)}`
});

// 直接预览（不推荐）
// uni.navigateTo({
//   url: `/pages/pdf-preview/pdf-preview?type=1&url=${encodeURIComponent(pdfUrl)}`
// });

4.2 参数说明

• type: 预览方式，1为直接预览，2为使用pdf.js（默认）
• url: 要预览的PDF文件URL，需要进行encodeURIComponent编码

5. 高级配置与优化

5.1 自定义pdf.js界面

pdf.js的viewer.html界面可以完全自定义。你可以：

1. 修改static/pdfjs/web/viewer.css来调整样式
2. 编辑viewer.html来改变布局结构
3. 通过URL参数控制初始显示效果

常用URL参数：

• zoom: 初始缩放比例（如zoom=page-width）
• pagemode: 页面模式（如pagemode=thumbs）
• nameddest: 跳转到指定位置

5.2 本地文件预览

如果需要预览本地文件，需要先将文件上传到临时目录：

javascript复制uni.chooseFile({
  success(res) {
    const tempFilePaths = res.tempFilePaths;
    uni.navigateTo({
      url: `/pages/pdf-preview/pdf-preview?type=2&url=${encodeURIComponent(tempFilePaths[0])}`
    });
  }
});

5.3 性能优化建议

对于大型PDF文件，可以采取以下优化措施：

1. 启用range请求：修改viewer.js中的disableRange为false
2. 调整渲染质量：通过设置pdf.js的渲染参数平衡质量和性能
3. 实现分页加载：只渲染当前可见页面

6. 常见问题与解决方案

6.1 跨域问题

如果PDF文件位于不同域名下，可能会遇到跨域限制。解决方案：

1. 确保服务器配置了正确的CORS头
2. 或者通过后端代理请求PDF文件

6.2 移动端适配

在移动设备上，建议：

1. 禁用文本选择（如果需要）
2. 调整默认缩放级别
3. 优化触摸事件处理

6.3 白屏问题排查

如果出现白屏，可以按以下步骤排查：

1. 检查控制台是否有错误
2. 确认pdf.js文件是否完整加载
3. 验证PDF文件URL是否可访问
4. 检查文件MIME类型是否为application/pdf

7. 替代方案比较

除了pdf.js，还有其他几种PDF预览方案：

1. 浏览器原生预览：

   • 优点：实现简单
   • 缺点：样式不可控，移动端体验差

2. PDFObject库：

   • 优点：轻量级
   • 缺点：功能有限

3. 商业PDF SDK：

   • 优点：功能强大
   • 缺点：需要付费

相比之下，pdf.js在功能和自由度之间取得了很好的平衡，特别适合需要自定义界面和功能的中大型项目。

8. 实际应用中的经验分享

在实际项目中应用pdf.js时，我总结了以下几点经验：

1. 版本控制：建议锁定pdf.js的特定版本，避免自动更新带来的兼容性问题。

2. 错误处理：完善错误处理逻辑，特别是对于加载失败的情况，要给用户友好的提示。

3. 性能监控：对于大型PDF文件，建议添加加载进度指示器。

4. 安全考虑：如果预览敏感文档，建议添加水印或禁用打印/下载功能。

5. 缓存策略：合理利用localStorage缓存PDF文件元数据，提升重复访问的体验。

一个实用的错误处理增强版实现：

javascript复制onLoad((options) => {
  // ...原有代码...
  
  // 添加web-view加载监听
  const handleLoad = () => {
    // 注入JS检测pdf.js是否加载成功
    const script = `
      setTimeout(() => {
        if (!window.PDFViewerApplication || !window.PDFViewerApplication.pdfViewer) {
          window.location.href = 'about:blank';
        }
      }, 3000);
    `;
    
    const currentWebview = this.$scope.$getAppWebview();
    currentWebview.evalJS(script);
  };
  
  this.$scope.$on('webviewLoad', handleLoad);
  this.$scope.$on('webviewError', () => {
    uni.showToast({ title: '加载失败', icon: 'none' });
  });
});

9. 扩展功能实现

基于pdf.js的核心功能，我们可以进一步扩展：

9.1 添加水印功能

修改viewer.js，在渲染时添加水印：

javascript复制// 在pdf.js的渲染流程中添加
PDFJS.AnnotationLayer.prototype.render = function(parameters) {
  // 原有渲染逻辑...
  
  // 添加水印
  const watermark = document.createElement('div');
  watermark.style.position = 'absolute';
  watermark.style.top = '0';
  watermark.style.left = '0';
  watermark.style.width = '100%';
  watermark.style.height = '100%';
  watermark.style.background = 'url("data:image/svg+xml,...") repeat';
  watermark.style.pointerEvents = 'none';
  parameters.div.appendChild(watermark);
};

9.2 实现PDF标注功能

利用pdf.js的注解API，可以实现：

1. 文本高亮
2. 添加注释
3. 绘制图形
4. 签名功能

9.3 集成文本搜索

pdf.js内置了全文搜索功能，可以通过以下方式调用：

javascript复制PDFViewerApplication.findController.executeCommand('find', {
  query: '搜索关键词',
  highlightAll: true,
  caseSensitive: false
});

10. 项目部署注意事项

在项目部署时，需要特别注意：

1. 静态资源路径：确保生产环境的静态资源路径配置正确。
2. CDN加速：对于大型PDF文件，建议使用CDN加速。
3. 缓存策略：合理配置HTTP缓存头，优化加载性能。
4. 安全策略：如果需要限制PDF访问权限，应该在后端实现验证逻辑。

一个典型的Nginx配置示例：

nginx复制location /static/pdfjs/ {
  alias /path/to/your/project/static/pdfjs/;
  expires 30d;
  add_header Cache-Control "public";
}

location /pdf-files/ {
  internal;  # 限制直接访问
  alias /path/to/secure/pdf/storage/;
  expires off;
  add_header Cache-Control "private";
}

11. 性能优化深度实践

11.1 延迟加载策略

对于多页PDF，可以实现按需加载：

javascript复制PDFViewerApplicationOptions.set('defaultRenderingQueue', {
  // 只渲染可见页面
  viewportLazy: true,
  // 预渲染前后2页
  preRenderPageCount: 2
});

11.2 内存管理

pdf.js可能会占用较多内存，特别是在移动设备上。可以通过以下方式优化：

1. 及时销毁不再需要的PDF文档实例
2. 限制同时渲染的页面数量
3. 使用web worker分担主线程压力

11.3 网络优化

针对网络环境较差的场景：

1. 实现分块加载（chunked loading）
2. 添加重试机制
3. 支持离线缓存

12. 测试与调试技巧

12.1 常用调试命令

在浏览器控制台中，可以直接调用pdf.js的API进行调试：

javascript复制// 获取当前PDF文档
PDFViewerApplication.pdfDocument

// 跳转到指定页面
PDFViewerApplication.page = 5

// 获取文档信息
PDFViewerApplication.pdfDocument.getMetadata()

12.2 常见问题排查

1. 字体显示异常：检查PDF是否嵌入了字体，或配置pdf.js的字体映射。
2. 渲染模糊：调整canvas的DPI设置。
3. 交互延迟：检查是否有过多的DOM事件监听。

12.3 自动化测试建议

对于PDF预览功能，建议实现以下测试用例：

1. 不同大小PDF文件的加载测试
2. 网络状况模拟测试（慢速/离线）
3. 跨域访问测试
4. 移动端手势操作测试
5. 内存泄漏检测

13. 未来发展与替代方案

随着Web技术的发展，PDF处理也出现了新的可能性：

1. WebAssembly方案：如PDFLib等库利用WASM获得更好性能
2. 服务端渲染：在服务端将PDF转为图片或SVG
3. Web Components：封装成可复用的PDF查看器组件

不过目前来看，pdf.js仍然是平衡性最好的解决方案，特别是对于需要深度定制的项目。