React PDF 查看器：安装、配置与使用

在现代的 Web 应用中，展示 PDF 文档是一个常见的需求。对于使用 React 构建的用户界面，react-pdf 是一个功能强大且广受欢迎的库，它允许开发者直接在 React 组件中渲染 PDF 文件，并提供对查看体验的细粒度控制。本文将详细介绍 react-pdf 的安装、配置和基本使用。

什么是 react-pdf？

react-pdf 是一个基于 PDF.js（Mozilla 开发的一个用于在浏览器中渲染 PDF 的 JavaScript 库）构建的 React 组件库。它将 PDF.js 的功能封装成易于使用的 React 组件，让开发者能够轻松地将 PDF 文档嵌入到自己的应用中，并进行自定义交互。

1. 安装 react-pdf

安装 react-pdf 非常简单，你可以使用 npm 或 yarn 将其添加到你的 React 项目中。打开你的终端，导航到你的项目根目录，然后执行以下命令：

“`bash

使用 npm 安装

npm install react-pdf

或者使用 yarn 安装

yarn add react-pdf
“`

安装完成后，react-pdf 及其依赖项将被添加到你的 node_modules 文件夹，并记录在 package.json 文件中。

2. 配置 react-pdf

react-pdf 依赖于 PDF.js 的 worker 脚本来高效地处理和渲染 PDF 文档。因此，在使用 react-pdf 之前，你需要配置 worker 脚本的路径。

通常，在你的主应用文件（例如 src/index.js 或 src/App.js）中添加以下配置：

“`javascript
import { pdfjs } from ‘react-pdf’;

// 配置 PDF.js worker 脚本的路径
// 推荐使用 CDN 链接，确保 worker 脚本在全球范围内的可用性
pdfjs.GlobalWorkerOptions.workerSrc = //unpkg.com/pdfjs-dist@${pdfjs.version}/build/pdf.worker.min.js;

// 其他你的应用代码…
“`

解释：

• pdfjs.GlobalWorkerOptions.workerSrc：这是 react-pdf 库用来查找 PDF.js worker 脚本的关键配置。
• //unpkg.com/pdfjs-dist@${pdfjs.version}/build/pdf.worker.min.js：这是一个 CDN 链接，它指向 react-pdf 当前版本所对应的 PDF.js worker 脚本。使用 CDN 可以避免在本地项目中打包 worker 脚本，并确保其始终可用。
• 重要提示： 请确保此配置在任何 Document 组件渲染之前执行，通常在应用的入口文件或顶层组件中设置是最佳实践。

此外，为了正确显示 PDF 的注释层和文本层，你需要导入 react-pdf 提供的样式文件：

javascript
import 'react-pdf/dist/esm/Page/AnnotationLayer.css';
import 'react-pdf/dist/esm/Page/TextLayer.css';

这些样式文件应该在你使用 Document 和 Page 组件的组件文件中或全局样式文件中导入。

3. 使用 react-pdf

react-pdf 主要通过两个核心组件来工作：Document 和 Page。

• Document 组件：用于加载 PDF 文档。
• Page 组件：嵌套在 Document 内部，用于渲染 PDF 文档的单个页面。

下面是一个基础示例，展示如何在一个 React 组件中显示 PDF 文档，并添加简单的页面导航功能：

“`javascript
import React, { useState } from ‘react’;
import { Document, Page, pdfjs } from ‘react-pdf’;
import ‘react-pdf/dist/esm/Page/AnnotationLayer.css’;
import ‘react-pdf/dist/esm/Page/TextLayer.css’;

// 确保在组件外部或应用的入口文件配置 workerSrc
// pdfjs.GlobalWorkerOptions.workerSrc = //unpkg.com/pdfjs-dist@${pdfjs.version}/build/pdf.worker.min.js;

function PDFViewer() {
const [numPages, setNumPages] = useState(null); // 总页数
const [pageNumber, setPageNumber] = useState(1); // 当前页码
const pdfFile = ‘./sample.pdf’; // PDF 文件路径，可以是本地文件、URL 或 Base64 字符串

// PDF 文档成功加载后的回调函数
function onDocumentLoadSuccess({ numPages }) {
setNumPages(numPages);
setPageNumber(1); // 每次加载新文档时，重置到第一页
}

// 改变页码的通用函数
function changePage(offset) {
setPageNumber(prevPageNumber => prevPageNumber + offset);
}

// 上一页
function previousPage() {
changePage(-1);
}

// 下一页
function nextPage() {
changePage(1);
}

return (

  {/* PDF 查看器区域 */}
  <div style={{ width: '100%', maxWidth: '800px', margin: '0 auto', border: '1px solid #ccc' }}>
    <Document
      file={pdfFile} // 指定要加载的 PDF 文件
      onLoadSuccess={onDocumentLoadSuccess} // PDF 成功加载后的回调
      // onLoadError={(error) => console.error('Error loading PDF:', error)} // 加载失败的回调
    >
      <Page
        pageNumber={pageNumber} // 指定要渲染的页码
        width={800} // 设置页面的宽度，高度将按比例调整
        // scale={1.0} // 可以通过 scale 属性调整缩放
      />
    </Document>
  </div>
  {/* 如果 PDF 未加载或有错误，可以显示提示 */}
  {!numPages && <p>正在加载 PDF...</p>}
  {numPages === null && <p>请选择一个 PDF 文件。</p>}
</div>