本文深入探讨使用 pdf.js 将 pdf 文档渲染到 canvas 时出现模糊的问题。通过分析官方 viewer 的渲染机制，我们发现关键在于精确计算 canvas 尺寸并应用 `transform` 渲染参数。本教程将提供详细的解决方案和代码示例，指导开发者如何优化 canvas 渲染，确保 pdf 内容在不同设备上呈现出清晰锐利的视觉效果。
PDF.js 是一个强大的 JavaScript 库，用于在 Web 浏览器中渲染 PDF 文档。它通常将 PDF 页面绘制到一个 HTML <canvas> 元素上。然而，开发者在使用 PDF.js 进行自定义渲染时，常会遇到一个普遍问题：渲染出的 PDF 页面在 Canvas 上显得模糊，尤其是在高 DPI（每英寸点数）显示器上，与官方 PDF.js Viewer 的清晰度存在明显差距。
问题分析：为什么渲染会模糊？
当我们将 PDF 页面直接渲染到 Canvas 时，如果 Canvas 的内部绘制尺寸（由 width 和 height 属性定义）与实际显示尺寸（由 CSS width 和 height 定义）不匹配，或者没有充分利用设备的高 DPI 能力，就可能导致模糊。官方 PDF.js Viewer 在渲染时，会进行一系列额外的计算和调整，以确保在不同显示器上都能提供最佳的视觉效果。
通过对 PDF.js 官方 viewer.js 源代码的深入分析，可以发现其解决模糊问题的核心在于两点：
- Canvas 尺寸的精确计算：根据设备的 devicePixelRatio 调整 Canvas 的内部绘制尺寸。
- renderContext 中的 transform 参数：在渲染时应用一个变换矩阵，以确保 PDF 内容能够以更高的分辨率绘制到 Canvas 的内部像素上，然后通过 CSS 缩放回原始显示尺寸。
解决方案：优化 Canvas 渲染参数
要解决 PDF.js 渲染模糊问题，我们需要调整 Canvas 的实际像素尺寸，并向 page.render() 方法传递一个 transform 数组。
1. 获取设备像素比 (Device Pixel Ratio)
window.devicePixelRatio 返回当前显示设备的物理像素分辨率与 CSS 像素分辨率之比。在高 DPI 屏幕（如 Retina 显示屏）上，这个值通常大于 1（例如 2 或 3）。为了获得清晰的渲染效果，我们需要让 Canvas 内部绘制的像素数与设备的物理像素数相匹配。
var outputScale = window.devicePixelRatio || 1;
2. 计算 Canvas 尺寸
首先，我们需要获取 PDF 页面的视口 (viewport)，它包含了页面的原始宽度和高度，以及应用了缩放因子后的尺寸。
var scale = 1.5; // 你可以根据需要调整渲染缩放比例
var viewport = page.getViewport({ scale: scale });然后，根据 outputScale 调整 Canvas 的实际 width 和 height 属性。同时，为了保持 Canvas 在页面上的视觉大小不变，我们需要通过 CSS 设置其 width 和 height 为原始视口的尺寸。
var canvas = document.getElementById('the-canvas');
var context = canvas.getContext('2d');
// 设置 Canvas 内部绘制尺寸，考虑设备像素比
canvas.height = Math.floor(viewport.height * outputScale);
canvas.width = Math.floor(viewport.width * outputScale);
// 通过 CSS 调整 Canvas 的显示尺寸，保持视觉大小不变
canvas.style.width = Math.floor(viewport.width) + 'px';
canvas.style.height = Math.floor(viewport.height) + 'px';3. 构建 transform 矩阵
transform 参数是一个包含六个元素的数组，代表一个 2D 变换矩阵 [a, b, c, d, e, f]。在 PDF.js 中，它用于在渲染时对页面内容进行额外的缩放和平移。为了实现高分辨率渲染并将其缩放到正确的显示尺寸，我们需要设置一个 transform 矩阵，将绘制操作从设备像素空间转换回 CSS 像素空间。
var transform = outputScale !== 1 ? [outputScale, 0, 0, outputScale, 0, 0] : null;
如果 outputScale 不为 1，则创建一个缩放矩阵 [outputScale, 0, 0, outputScale, 0, 0]。这意味着在绘制到 Canvas 上时，内容会放大 outputScale 倍。由于 Canvas 已经被设置了更大的内部像素尺寸，这种放大可以充分利用这些额外的像素。
4. 渲染页面
最后，将调整后的 transform 参数传递给 page.render() 方法。
var renderContext = {
canvasContext: context,
viewport: viewport,
transform: transform // 添加 transform 参数
};
var renderTask = page.render(renderContext);
renderTask.promise.then(function () {
console.log('Page rendered clearly');
});完整代码示例
以下是结合上述步骤的完整 HTML 和 JavaScript 代码示例：
<!DOCTYPE html>
<html>
<head>
<title>PDF.js 清晰渲染示例</title>
<style>
body { margin: 0; padding: 20px; font-family: sans-serif; }
canvas { border: 1px solid #ccc; display: block; margin: 0 auto; }
</style>
</head>
<body>
<h1>PDF.js 清晰渲染示例</h1>
<canvas id="the-canvas"></canvas>
<script src="https://mozilla.github.io/pdf.js/build/pdf.js"></script>
<script>
// PDF 文件的 URL
var url = 'https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf';
// 获取 PDF.js 库的引用
var pdfjsLib = window['pdfjs-dist/build/pdf'];
// 必须指定 workerSrc 属性，指向 pdf.worker.js 文件的路径
pdfjsLib.GlobalWorkerOptions.workerSrc = 'https://mozilla.github.io/pdf.js/build/pdf.worker.js';
// 异步下载 PDF
var loadingTask = pdfjsLib.getDocument(url);
loadingTask.promise.then(function(pdf) {
console.log('PDF loaded');
// 获取第一页
var pageNumber = 1;
pdf.getPage(pageNumber).then(function(page) {
console.log('Page loaded');
var scale = 1.5; // 渲染比例，可根据需要调整
var viewport = page.getViewport({ scale: scale });
// 获取 Canvas 元素和其 2D 渲染上下文
var canvas = document.getElementById('the-canvas');
var context = canvas.getContext('2d');
// 获取设备像素比，用于高 DPI 屏幕优化
var outputScale = window.devicePixelRatio || 1;
// 根据设备像素比调整 Canvas 的内部绘制尺寸（物理像素）
canvas.height = Math.floor(viewport.height * outputScale);
canvas.width = Math.floor(viewport.width * outputScale);
// 通过 CSS 调整 Canvas 的显示尺寸（CSS 像素），以保持视觉大小不变
canvas.style.width = Math.floor(viewport.width) + 'px';
canvas.style.height = Math.floor(viewport.height) + 'px';
// 构建 transform 矩阵，用于在渲染时进行内部缩放
// 如果 outputScale 不为 1，则应用缩放矩阵
var transform = outputScale !== 1 ? [outputScale, 0, 0, outputScale, 0, 0] : null;
// 配置渲染上下文，传入 transform 参数
var renderContext = {
canvasContext: context,
viewport: viewport,
transform: transform // 传递 transform 参数
};
// 渲染 PDF 页面到 Canvas
var renderTask = page.render(renderContext);
renderTask.promise.then(function () {
console.log('Page rendered clearly');
});
});
}, function (reason) {
// PDF 加载错误处理
console.error('Error: ' + reason);
});
</script>
</body>
</html>注意事项与总结
- 设备像素比 (DPR) 的重要性：理解并应用 window.devicePixelRatio 是解决高 DPI 屏幕上模糊问题的关键。它允许 Canvas 内部以更高的分辨率进行绘制，从而充分利用显示器的物理像素。
- CSS 尺寸与实际像素尺寸分离：通过设置 canvas.width/height 为高分辨率值，同时通过 canvas.style.width/height 设置为期望的显示尺寸，可以实现高分辨率渲染和正确的视觉大小。
- transform 参数的作用：transform 矩阵在渲染过程中起到了一个内部缩放的作用，确保 PDF 内容在绘制到高分辨率 Canvas 上时能够正确地被放大，以匹配 Canvas 的内部像素密度。
- 性能考量：渲染更高分辨率的图像会消耗更多的 CPU 和内存资源。在处理大量页面或非常大的 PDF 文件时，应权衡清晰度和性能。可以考虑在低性能设备或特定场景下，将 outputScale 限制在一个合理的值。
- 多页文档处理：对于多页文档，上述逻辑需要封装成一个函数，并在遍历每一页时应用。
通过上述方法，开发者可以显著提升 PDF.js 在 Canvas 上渲染 PDF 文档的清晰度，使其与官方 Viewer 的显示效果保持一致，从而为用户提供更优质的阅读体验。
