使用 `react-pdf-js` 在 React 中渲染 PDF 文档

1. 项目介绍

react-pdf-js 是一个React组件，它提供了一个方便的包装器来使用PDF.js库进行PDF文档的渲染。该项目由Mike Cousins开发并维护，其目的是简化在React应用中集成PDF查看的功能。react-pdf-js 支持 TypeScript 并且可以很好地配合 Vite 和 tsup 这类构建工具。

特点

• 提供React组件以轻松集成PDF查看
• 支持PDF.js的PDFDocumentProxy和PDFPageProxy对象
• 兼容ES6语法
• 开源，遵循MIT许可证

官方资源

• 项目主页
• Readme文档
• 示例应用

2. 项目快速启动

安装依赖

确保你的项目已经安装了react, react-dom以及pdfjs-dist。如果没有，可以通过下面的命令添加：

npm install --save react react-dom pdfjs-dist
# 或者使用Yarn
yarn add react react-dom pdfjs-dist

接下来安装react-pdf-js：

npm install --save @mikecousins/react-pdf
# 或者使用Yarn
yarn add @mikecousins/react-pdf

引入并使用

在你的React组件中引入usePdf钩子：

import React from 'react';
import { usePdf } from '@mikecousins/react-pdf';

function PdfViewer() {
  // 使用usePdf钩子加载PDF文件
  const { pdfDocument, pdfPage } = usePdf({
    url: 'path/to/your/pdf/file.pdf', // 替换为实际PDF路径或URL
  });

  return (
    <div>
      {/* 当PDF页面加载成功时显示 */}
      {pdfPage && <canvas ref={pdfPage.render} />}
    </div>
  );
}

export default PdfViewer;

注意：pdfPage.render需要传递一个ref到<canvas>元素以便于渲染PDF页面。实际应用中可能需要处理加载错误和等待加载状态。

3. 应用案例和最佳实践

错误处理

为了处理可能出现的加载失败情况，可以在usePdf钩子的返回值中捕获错误：

function PdfViewer() {
  const [error, setError] = useState(null);

  const { pdfDocument, pdfPage } = usePdf({
    url: 'path/to/your/pdf/file.pdf',
  }, {
    onError: (err) => setError(err),
  });

  return (
    <>
      {error ? <div>加载PDF出错：{error.message}</div> : null}
      {pdfPage && <canvas ref={pdfPage.render} />}
    </>
  );
}

自定义渲染器

如果你想自定义PDF的渲染方式，可以利用pdfPage.render方法传入自定义的参数：

const canvasRef = useRef(null);
pdfPage.render(canvasRef.current, {
  viewport: pdfPage.getViewport({ scale: 1 }),
});

4. 典型生态项目

• PDF.js: react-pdf-js 的基础库，用于处理PDF文档的核心功能。
• Vite: 一个现代化的前端构建工具，可与react-pdf-js无缝协作。
• tsup: 一个简单的TypeScript打包工具，适用于快速构建小体积的生产包。
• Create React App: 无需配置即可快速创建React应用，也支持react-pdf-js。

通过以上内容，你应该能顺利地将react-pdf-js整合到你的React项目中，实现PDF文档的展示和交互功能。更多信息和详细文档请参考项目GitHub页面。