当前位置：首页 > news >正文

使用 CDN 在国内加载本地 PDF 文件并处理批注：PDF.js 5.x 实战指南

news 来源：原创 2025/5/9 7:42:46

PDF.js 是一个强大的开源 JavaScript 库，用于在 Web 浏览器中渲染 PDF 文件。它由 Mozilla 开发，能够将 PDF 文档绘制到 HTML5 Canvas 或 SVG 上，无需任何本机代码或浏览器插件。对于许多需要在网页中展示 PDF 内容的应用场景来说，PDF.js 是一个非常理想的选择。

本文将重点探讨以下几个方面：

如何通过 CDN 在网页中引入 PDF.js 库。
在中国大陆地区选择哪些 CDN 服务以获得更好的访问速度和稳定性。
如何使用 PDF.js 加载用户选择的本地 PDF 文件。
PDF.js 如何处理 PDF 文件中的批注，以及在使用批注功能时需要注意的事项。

我们将以 PDF.js 5.x 版本为例进行讲解，但核心原理同样适用于其他版本。

1. 通过 CDN 引入 PDF.js

使用 CDN (内容分发网络) 引入 PDF.js 是最常见和便捷的方式，它可以减轻服务器压力，并利用 CDN 节点的地理优势加速文件的传输。引入 PDF.js 主要需要两个文件：

pdf.min.js: PDF.js 的核心库，包含了主要的 API 和渲染逻辑。
pdf.worker.min.js: PDF.js 的 Worker 脚本，用于在后台线程中处理 PDF 的解析和渲染任务，避免阻塞主线程。

你需要在 HTML 文件的 <head> 或 <body> 标签中引入它们：

<script src="[CDN_URL_FOR_PDF.MIN.JS]"></script>
<script>// 必须设置 workerSrc 指向 worker 脚本的 URLpdfjsLib.GlobalWorkerOptions.workerSrc = '[CDN_URL_FOR_PDF.WORKER.MIN.JS]';
</script>

请将 [CDN_URL_FOR_PDF.MIN.JS] 和 [CDN_URL_FOR_PDF.WORKER.MIN.JS] 替换为实际的 CDN 链接。注意，workerSrc 必须设置，并且核心库和 worker 脚本的版本号必须严格匹配。

2. 中国大陆地区 CDN 选择建议

对于在中国大陆地区访问的用户，受限于网络环境，直接使用一些国际 CDN（如 Cloudflare CDN）可能会遇到访问速度慢或不稳定的问题。为了获得更好的用户体验，建议选择在中国有部署节点或与中国本地服务商有合作的 CDN。

以下是两个在中国大陆地区表现通常较好的开源库 CDN：

a. jsDelivr

jsDelivr 是一个免费的、高速的开源 CDN，它与中国的网宿、七牛云等服务商有深度合作，拥有广泛的中国大陆节点。对于开源库来说，jsDelivr 是一个非常可靠的选择。

你可以在 jsDelivr 上通过 npm/package-name@version/file-path 的格式找到 PDF.js 的文件。PDF.js 的 npm 包名是 pdfjs-dist。

例如，如果你需要引入接近 5.x 的某个稳定版本，你需要查找具体的版本号（请注意，pdf.js 版本号通常是构建号，例如 4.0.269 是一个近期版本，请替换为你实际需要的 5.x 对应的版本号）：

核心库 (pdf.min.js):
https://cdn.jsdelivr.net/npm/pdfjs-dist@版本号/build/pdf.min.js
例：https://cdn.jsdelivr.net/npm/pdfjs-dist@4.0.269/build/pdf.min.js
Worker 脚本 (pdf.worker.min.js):
https://cdn.jsdelivr.net/npm/pdfjs-dist@版本号/build/pdf.worker.min.js
例：https://cdn.jsdelivr.net/npm/pdfjs-dist@4.0.269/build/pdf.worker.min.js

请访问 jsDelivr 官网或利用其搜索功能，查找 pdfjs-dist 包下您需要的具体 5.x 版本号和文件路径。

b. BootCDN

BootCDN 是一个由国内团队维护的、专注于服务国内开发者的开源库 CDN 平台。它同步了许多国外常用开源库的资源，并使用国内的 CDN 服务商提供加速。

你可以在 BootCDN 上搜索 “pdf.js” 或 “pdfjs-dist” 来找到对应的资源。BootCDN 的 URL 格式通常是 cdn.bootcdn.net/ajax/libs/library-name/version/file-path。

例如，如果你需要引入接近 5.x 的某个版本（同样，请替换为你实际需要的 5.x 对应的版本号）：

核心库 (pdf.min.js):
https://cdn.bootcdn.net/ajax/libs/pdf.js/版本号/pdf.min.js
例：https://cdn.bootcdn.net/ajax/libs/pdf.js/4.0.269/pdf.min.js
Worker 脚本 (pdf.worker.min.js):
https://cdn.bootcdn.net/ajax/libs/pdf.js/版本号/pdf.worker.min.js
例：https://cdn.bootcdn.net/ajax/libs/pdf.js/4.0.269/pdf.worker.min.js

请访问 BootCDN 官网查找您需要的 pdf.js 版本对应的具体文件路径。

重要： 在选择 CDN 后，请务必替换 HTML 中的 [CDN_URL_FOR_PDF.MIN.JS] 和 [CDN_URL_FOR_PDF.WORKER.MIN.JS] 为您选择的 CDN 提供的实际链接，并确保两个文件的版本号一致。

3. 加载本地 PDF 文件

PDF.js 可以通过多种方式加载 PDF 源，包括 URL、 TypedArray (如 ArrayBuffer)、以及 Blob。要加载本地文件，最常用的方式是结合 <input type="file"> 和 FileReader API，将文件读取为 ArrayBuffer，然后传递给 PDF.js。

首先，在 HTML 中添加一个用于用户选择本地文件的输入框，以及一个用于渲染 PDF 的 canvas 元素：

<input type="file" id="pdfFile" accept=".pdf">
<canvas id="the-canvas"></canvas>

然后，使用 JavaScript 监听文件输入框的 change 事件，读取文件内容并使用 PDF.js 加载和渲染：

document.getElementById('pdfFile').addEventListener('change', function(event) {var file = event.target.files[0]; // 获取用户选择的第一个文件// 检查文件类型if (file.type !== "application/pdf") {alert(file.name + " 不是一个有效的 PDF 文件。");return;}var fileReader = new FileReader();// 当文件读取完成后fileReader.onload = function() {// 文件内容作为 ArrayBuffervar typedarray = new Uint8Array(this.result);// 使用 PDF.js 加载 PDF 文档const loadingTask = pdfjsLib.getDocument(typedarray);loadingTask.promise.then(function(pdf) {console.log('PDF 加载成功');// 以第一页为例进行渲染pdf.getPage(1).then(function(page) {console.log('页面加载成功');var scale = 1.5; // 缩放比例var viewport = page.getViewport({ scale: scale });// 获取 canvas 元素及其上下文var canvas = document.getElementById('the-canvas');var context = canvas.getContext('2d');// 设置 canvas 的尺寸与页面 viewport 匹配canvas.height = viewport.height;canvas.width = viewport.width;// 渲染页面到 canvasvar renderContext = {canvasContext: context,viewport: viewport};var renderTask = page.render(renderContext);renderTask.promise.then(function() {console.log('页面渲染完成');});});}, function(reason) {// PDF 加载失败的处理console.error('PDF 加载失败: ' + reason);});};// 读取文件内容为 ArrayBufferfileReader.readAsArrayBuffer(file);
});

这段代码演示了如何加载用户选择的本地 PDF 文件，并将其第一页渲染到页面上指定的 canvas 元素中。你可以根据需要扩展代码，实现多页加载、滚动、缩放等功能。

4. 关于批注功能

当涉及到 PDF 批注时，需要明确一点：PDF.js 的核心功能是渲染和显示 PDF 文档内容，这包括显示 PDF 文件本身已经包含的标准批注类型（如文本标记、高亮、形状等）。

但是，PDF.js (包括 5.x 版本) 本身并不提供创建**、编辑或保存新批注的内置交互式工具或 API。**

这意味着：

如果你加载的本地 PDF 文件本身已经包含了批注，PDF.js 在渲染时会尝试将其显示出来。通常情况下，如果批注是标准的 PDF 批注类型，它们会随着页面内容一起被绘制到 Canvas 上，或者作为独立的图层数据提供（需要进一步处理）。
如果你希望实现用户在网页上添加、修改或删除批注的功能，仅仅依靠 PDF.js 的核心库是不够的。你需要自己实现一套完整的批注交互逻辑和数据管理系统。这通常非常复杂，需要：
- 监听鼠标事件，识别用户在 Canvas 上的操作。
- 在 Canvas 上方叠加一个交互层（例如另一个 Canvas 或 SVG）来绘制批注的图形表示。
- 根据用户操作，创建或修改批注的数据结构。
- 将这些批注数据保存下来，如果需要保存回 PDF 文件本身，则需要更高级的库（如 PDF-LIB，它可以在浏览器端修改 PDF 文件，但功能有限）或依赖后端服务来处理 PDF 文件的修改。

建议：

如果你的需求是实现功能完善的交互式批注工具，考虑到其复杂性，你可能需要：

深入研究 PDF.js 的底层 API 如何获取批注信息，并结合 Canvas 或 SVG 绘图技术自行实现批注的绘制和交互逻辑。
考虑使用第三方的 JavaScript PDF SDK 或库，这些库通常基于 PDF.js 或其他渲染引擎构建，并提供了开箱即用的批注创建、编辑和保存功能。一些库声称与 PDF.js 兼容，或者提供了更高级的 API 来处理 PDF 文档的结构和批注。