React-PDF

在您的React应用中像显示图片一样轻松地显示PDF。

迷路了？

这个包是用来"显示"已有的PDF。如果您想用React"创建"PDF，您可能在找@react-pdf/renderer。

简要说明

• 通过执行npm install react-pdf或yarn add react-pdf安装。
• 通过添加import { Document } from 'react-pdf'导入。
• 通过添加<Document file="..." />使用。file可以是URL、base64内容、Uint8Array等。
• 在<Document />内放置<Page />组件来渲染页面。

演示

在sample目录中可以找到一个最小化的演示页面。

也可以查看在线演示！

在继续之前

React-PDF正在持续开发中。本文档是为React-PDF 9.x分支编写的。如果您想查看其他版本的React-PDF文档，请使用GitHub页面顶部的下拉菜单切换到适当的标签。以下是每个分支最新文档的快速链接：

• v8.x
• v7.x
• v6.x
• v5.x
• v4.x
• v3.x
• v2.x
• v1.x

入门

兼容性

浏览器支持

React-PDF支持所有现代浏览器。它已在Chrome、Edge、Safari、Firefox和Opera的最新版本中进行了测试。

React-PDF v9默认支持以下浏览器：

• Chrome ≥119
• Edge ≥119
• Safari ≥17.4
• Firefox ≥121

您可以通过提供额外的polyfills（例如Array.prototype.at、Promise.allSettled或Promise.withResolvers）并配置您的打包工具以转译pdfjs-dist或使用旧版PDF.js worker来扩展支持的浏览器列表。

如果您需要支持更旧的浏览器，您需要使用React-PDF v6或更早版本。

React

要使用最新版本的React-PDF，您的项目需要使用React 16.8或更高版本。

如果您使用的是较旧版本的React，请参考下表找到合适的React-PDF版本。

Preact

React-PDF可以与Preact一起使用。

安装

通过执行npm install react-pdf或yarn add react-pdf将React-PDF添加到您的项目中。

Next.js

如果您使用Next.js且未启用Turbopack，请在您的next.config.js中添加以下内容：

module.exports = {
+ webpack: (config) => {
+   config.resolve.alias.canvas = false;

+   return config;
+ },
}

如果您使用Next.js且启用了Turbopack，请添加empty-module.ts文件：

export default {};

并在您的next.config.js中添加以下内容：

module.exports = {
+ experimental: {
+   turbo: {
+     resolveAlias: {
+       canvas: './empty-module.ts',
+     },
+   },
+ },
};

配置PDF.js worker

为了使React-PDF正常工作，需要提供PDF.js worker。您有几个选择。

导入worker（推荐）

对于大多数情况，以下示例将起作用：

import { pdfjs } from 'react-pdf';

pdfjs.GlobalWorkerOptions.workerSrc = new URL(
  'pdfjs-dist/build/pdf.worker.min.mjs',
  import.meta.url,
).toString();

[!注意] 在Next.js中：

• 使用App Router时，确保在文件顶部添加'use client';。
• 使用Pages Router时，确保在导入使用此代码的组件时禁用SSR。

[!注意] pnpm需要一个包含public-hoist-pattern[]=pdfjs-dist的.npmrc文件才能正常工作。

 pdfjs.GlobalWorkerOptions.workerSrc = new URL(
-  'pdfjs-dist/build/pdf.worker.min.mjs',
+  'npm:pdfjs-dist/build/pdf.worker.min.mjs',
   import.meta.url,
 ).toString();

将worker复制到public目录

您需要自行确保pdfjs-dist/build中的pdf.worker.mjs文件被复制到项目的输出文件夹中。

例如，您可以使用自定义脚本：

import path from 'node:path';
import fs from 'node:fs';

const pdfjsDistPath = path.dirname(require.resolve('pdfjs-dist/package.json'));
const pdfWorkerPath = path.join(pdfjsDistPath, 'build', 'pdf.worker.mjs');

fs.cpSync(pdfWorkerPath, './dist/pdf.worker.mjs', { recursive: true });

使用外部CDN

import { pdfjs } from 'react-pdf';

pdfjs.GlobalWorkerOptions.workerSrc = `//unpkg.com/pdfjs-dist@${pdfjs.version}/build/pdf.worker.min.mjs`;

旧版PDF.js worker

如果您需要支持较旧的浏览器，可以使用旧版PDF.js worker。要这样做，请按照上述说明进行操作，但在PDF.js worker导入路径中将/build/替换为legacy/build/，例如：

 pdfjs.GlobalWorkerOptions.workerSrc = new URL(
-  'pdfjs-dist/build/pdf.worker.min.mjs',
+  'pdfjs-dist/legacy/build/pdf.worker.min.mjs',
   import.meta.url,
 ).toString();

或：

-pdfjs.GlobalWorkerOptions.workerSrc = `//unpkg.com/pdfjs-dist@${pdfjs.version}/build/pdf.worker.min.mjs`;
+pdfjs.GlobalWorkerOptions.workerSrc = `//unpkg.com/pdfjs-dist@${pdfjs.version}/legacy/build/pdf.worker.min.mjs`;

使用

以下是基本用法的示例：

import { useState } from 'react';
import { Document, Page } from 'react-pdf';

function MyApp() {
  const [numPages, setNumPages] = useState<number>();
  const [pageNumber, setPageNumber] = useState<number>(1);

  function onDocumentLoadSuccess({ numPages }: { numPages: number }): void {
    setNumPages(numPages);
  }
返回 (
  <div>
    <Document file="somefile.pdf" onLoadSuccess={onDocumentLoadSuccess}>
      <Page pageNumber={pageNumber} />
    </Document>
    <p>
      第 {pageNumber} 页，共 {numPages} 页
    </p>
  </div>
);
}

请查看本仓库中的 sample 目录以获取完整的工作示例。更多示例和更高级的用例，请查看 React-PDF Wiki 中的 Recipes。

支持注释

如果你想在 React-PDF 渲染的 PDF 中使用注释（例如链接），那么你需要包含必要的样式表以正确显示注释，如下所示：

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

支持文本层

如果你想在 React-PDF 渲染的 PDF 中使用文本层，那么你需要包含必要的样式表以正确显示文本层，如下所示：

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

支持非拉丁字符

如果你想确保包含非拉丁字符的 PDF 能够完美渲染，或者你遇到了以下警告：

警告：必须指定 CMap "baseUrl" 参数，请确保提供了 "cMapUrl" 和 "cMapPacked" API 参数。

那么你还需要在你的构建中包含 cMaps，并告诉 React-PDF 它们的位置。

复制 cMaps

首先，你需要从 pdfjs-dist（React-PDF 的依赖项 - 如果你已安装 React-PDF，它应该在你的 node_modules 中）复制 cMaps。cMaps 位于 pdfjs-dist/cmaps。

Vite

通过执行 npm install vite-plugin-static-copy --save-dev 或 yarn add vite-plugin-static-copy --dev 添加 vite-plugin-static-copy，并在你的 Vite 配置中添加以下内容：

+import path from 'node:path';
+import { createRequire } from 'node:module';

-import { defineConfig } from 'vite';
+import { defineConfig, normalizePath } from 'vite';
+import { viteStaticCopy } from 'vite-plugin-static-copy';

+const require = createRequire(import.meta.url);
+
+const pdfjsDistPath = path.dirname(require.resolve('pdfjs-dist/package.json'));
+const cMapsDir = normalizePath(path.join(pdfjsDistPath, 'cmaps'));

export default defineConfig({
  plugins: [
+   viteStaticCopy({
+     targets: [
+       {
+         src: cMapsDir,
+         dest: '',
+       },
+     ],
+   }),
  ]
});

Webpack

通过执行 npm install copy-webpack-plugin --save-dev 或 yarn add copy-webpack-plugin --dev 添加 copy-webpack-plugin，并在你的 Webpack 配置中添加以下内容：

+import path from 'node:path';
+import CopyWebpackPlugin from 'copy-webpack-plugin';

+const pdfjsDistPath = path.dirname(require.resolve('pdfjs-dist/package.json'));
+const cMapsDir = path.join(pdfjsDistPath, 'cmaps');

module.exports = {
  plugins: [
+   new CopyWebpackPlugin({
+     patterns: [
+       {
+         from: cMapsDir,
+         to: 'cmaps/'
+       },
+     ],
+   }),
  ],
};

其他工具

如果你使用其他打包工具，你需要自行确保 cMaps 被复制到你项目的输出文件夹中。

例如，你可以使用自定义脚本，如：

import path from 'node:path';
import fs from 'node:fs';

const pdfjsDistPath = path.dirname(require.resolve('pdfjs-dist/package.json'));
const cMapsDir = path.join(pdfjsDistPath, 'cmaps');

fs.cpSync(cMapsDir, 'dist/cmaps/', { recursive: true });

设置 React-PDF

现在你的构建中已经有了 cMaps，通过使用 options 属性向 Document 组件传递所需的选项，如下所示：

// 在 React 组件外部
const options = {
  cMapUrl: '/cmaps/',
};

// 在 React 组件内部
<Document options={options} />;

[!注意] 确保在你的 React 组件外部定义 options 对象，如果不能，请使用 useMemo。

或者，你可以使用外部 CDN 的 cMaps：

// 在 React 组件外部
import { pdfjs } from 'react-pdf';

const options = {
  cMapUrl: `https://unpkg.com/pdfjs-dist@${pdfjs.version}/cmaps/`,
};

// 在 React 组件内部
<Document options={options} />;

支持标准字体

如果你想支持使用标准字体的 PDF（在 PDF 1.5 中已弃用，但仍在使用），或者你遇到了以下警告：

必须指定标准字体 "baseUrl" 参数，请确保提供了 "standardFontDataUrl" API 参数。

那么你还需要在你的构建中包含标准字体，并告诉 React-PDF 它们的位置。

复制字体

首先，你需要从 pdfjs-dist（React-PDF 的依赖项 - 如果你已安装 React-PDF，它应该在你的 node_modules 中）复制标准字体。标准字体位于 pdfjs-dist/standard_fonts。

Vite

通过执行 npm install vite-plugin-static-copy --save-dev 或 yarn add vite-plugin-static-copy --dev 添加 vite-plugin-static-copy，并在你的 Vite 配置中添加以下内容：

+import path from 'node:path';
+import { createRequire } from 'node:module';

-import { defineConfig } from 'vite';
+import { defineConfig, normalizePath } from 'vite';
+import { viteStaticCopy } from 'vite-plugin-static-copy';

+const require = createRequire(import.meta.url);
+const standardFontsDir = normalizePath(
+  path.join(path.dirname(require.resolve('pdfjs-dist/package.json')), 'standard_fonts')
+);

export default defineConfig({
  plugins: [
+   viteStaticCopy({
+     targets: [
+       {
+         src: standardFontsDir,
+         dest: '',
+       },
+     ],
+   }),
  ]
});

Webpack

通过执行 npm install copy-webpack-plugin --save-dev 或 yarn add copy-webpack-plugin --dev 添加 copy-webpack-plugin，并在你的 Webpack 配置中添加以下内容：

+import path from 'node:path';
+import CopyWebpackPlugin from 'copy-webpack-plugin';

+const standardFontsDir = path.join(path.dirname(require.resolve('pdfjs-dist/package.json')), 'standard_fonts');

module.exports = {
  plugins: [
+   new CopyWebpackPlugin({
+     patterns: [
+       {
+         from: standardFontsDir,
+         to: 'standard_fonts/'
+       },
+     ],
+   }),
  ],
};

其他工具

如果你使用其他打包工具，你需要自行确保标准字体被复制到你项目的输出文件夹中。

例如，你可以使用自定义脚本，如：

import path from 'node:path';
import fs from 'node:fs';

const pdfjsDistPath = path.dirname(require.resolve('pdfjs-dist/package.json'));
const standardFontsDir = path.join(pdfjsDistPath, 'standard_fonts');

fs.cpSync(standardFontsDir, 'dist/standard_fonts/', { recursive: true });

设置 React-PDF

现在你的构建中已经有了标准字体，通过使用 options 属性向 Document 组件传递所需的选项，如下所示：

// 在 React 组件外部
const options = {
  standardFontDataUrl: '/standard_fonts/',
};

// 在 React 组件内部
<Document options={options} />;

[!注意] 确保在你的 React 组件外部定义 options 对象，如果不能，请使用 useMemo。

或者，你可以使用外部 CDN 的标准字体：

// 在 React 组件外部
import { pdfjs } from 'react-pdf';
const options = {
  standardFontDataUrl: `https://unpkg.com/pdfjs-dist@${pdfjs.version}/standard_fonts`,
};

// React 组件内部
<Document options={options} />;

用户指南

Document

加载通过 file 属性传递的文档。

属性

Page

显示一个页面。应放置在 <Document /> 内部。或者，也可以传递 pdf 属性，该属性可以从 <Document /> 的 onLoadSuccess 回调函数中获取，但一些高级功能（如渲染注释和文档内页面之间的链接）可能无法正常工作。

属性

大纲

显示大纲(目录)。应放置在 <Document /> 内部。或者,可以传递 pdf 属性,该属性可以从 <Document /> 的 onLoadSuccess 回调函数中获得。

属性

缩略图

显示页面的缩略图。不渲染注释层或文本层。不将自身注册为链接目标,因此用户点击内部链接(例如目录中的链接)时不会滚动到缩略图组件。点击时,尝试导航到被点击的页面(类似于大纲中的链接)。应放置在 <Document /> 内部。或者,可以传递 pdf 属性,该属性可以从 <Document /> 的 onLoadSuccess 回调函数中获得。

属性

属性与 <Page /> 组件相同,但某些与注释层和文本层相关的属性不可用:

• customTextRenderer
• onGetAnnotationsError
• onGetAnnotationsSuccess
• onGetTextError
• onGetTextSuccess
• onRenderAnnotationLayerError
• onRenderAnnotationLayerSuccess
• onRenderTextLayerError
• onRenderTextLayerSuccess
• renderAnnotationLayer
• renderForms
• renderTextLayer

此外,还提供了额外的属性:

有用链接

• React-PDF Wiki

许可证

MIT 许可证。

作者

Wojciech Maj

致谢

如果没有 Niklas Närhinen 创建的原始版本以及 Mozilla 开发的 pdf.js,这个项目是不可能实现的。感谢你们!

赞助商

感谢所有赞助商,您的图片将出现在我们的 GitHub README 上。

支持者

感谢所有支持者,您的图片将出现在我们的 GitHub README 上。

主要贡献者

感谢所有为这个项目做出贡献的人!