React PDF 预览终极优化：30 页大文件不卡，加载快如闪电！
在前端开发中，PDF 预览是个常见需求。简单粗暴的方案是用
为什么需要自定义 PDF 预览？
先说说需求场景。假设你有个文件管理系统，用户上传 PDF 后需要在线预览。你可能会直接写：
这行代码确实能用，但问题不少：
- 样式控制弱：背景、边框不好调整，工具栏难以隐藏。
- 交互性差：没有翻页按钮、缩放功能，用户体验一般。
- 功能单一：无法动态调整页面大小或全屏展示。
而我们的 PDFView 组件，基于 react-pdf，用 React 的方式解决问题，提供更灵活的控制和更优雅的体验。接下来，我们拆解它的代码，看看它是怎么“打败”
核心代码拆解：从设计到实现
问题驱动开发
初版本的痛点：
- 性能瓶颈：大文件一次性加载全部页面，内存占用高，加载慢。
- 功能缺失：没有页面旋转，方向不对只能干瞪眼；没有多页预览，翻页全靠手动。
这些问题在实际场景中很常见。比如，用户上传一个 50 页的合同 PDF，如果加载卡顿，或者需要旋转查看签名页，原始版本就有点“力不从心”。优化后的 PDFView 将通过分页加载提升性能，新增旋转和缩略图功能，让体验飞起来！
优化后的核心实现
1. 性能优化：分页加载
- 问题：原始版本用
一次性加载所有页面，大文件时容易卡顿。 - 解决：引入 loadedPages 状态（Set 类型），只加载当前页和用户访问过的页面。
- 实现：
- 初始化仅加载第 1 页。
- 用户翻页或跳转时动态添加加载页面。
- 缩略图模式下未加载页面显示占位符，点击时加载。
useEffect(() => {
if (pageNumber && !loadedPages.has(pageNumber)) {
setLoadedPages(prev => new Set(prev).add(pageNumber));
}
}, [pageNumber]);2. 功能增强：页面旋转
- 需求：支持用户调整页面方向（比如横向文档）。
- 实现：
- 新增 rotation 状态，默认 0°。
- 提供 rotateLeft（-90°）和 rotateRight（+90°）函数。
- 通过 Page 组件的 rotate 属性应用旋转。
const rotateLeft = () => setRotation((prev) => (prev - 90) % 360);
const rotateRight = () => setRotation((prev) => (prev + 90) % 360);3. 功能增强：多页预览
- 需求：用户想快速浏览所有页面，像缩略图一样。
- 实现：
- 新增 showThumbnails 状态，切换单页和缩略图模式。
- 缩略图模式下渲染所有页面（小尺寸），点击跳转到对应页。
{showThumbnails ? (
{Array.from({ length: numPages }, (_, i) => i + 1).map((page) => (
{ setPageNumber(page); setShowThumbnails(false); }}>
{loadedPages.has(page) ? (
4. 按需加载：只渲染当前页
- 思路：用 visiblePages 控制渲染页面，初始只加载元信息，动态加载当前页。
- 实现：
- 移除 loadedPages，用 visiblePages 精确控制。
- 单页模式只渲染 pageNumber，缩略图模式限制前后几页。
useEffect(() => {
if (!showThumbnails) {
setVisiblePages([pageNumber]);
} else {
const start = Math.max(1, pageNumber - 2);
const end = Math.min(numPages, pageNumber + 2);
setVisiblePages(Array.from({ length: end - start + 1 }, (_, i) => start + i));
}
}, [pageNumber, showThumbnails, numPages]);5. 禁用多余渲染：轻量化页面
- 思路：关闭文本层和注释层，只渲染图像内容。
- 实现：在
组件中设置 renderTextLayer={false} 和 renderAnnotationLayer={false}。
6. 优化缩略图：避免过载
- 思路：缩略图模式下不一次性加载所有页面，用占位符替代未加载页。
- 实现：仅渲染当前页附近的页面，其他显示静态文本。
-
{visiblePages.includes(page) ? (} renderTextLayer={false} renderAnnotationLayer={false} /> ) : ( 第 {page} 页)}
展示完整代码
import React, { useEffect, useRef, useState, useCallback } from 'react';
import { createPortal } from 'react-dom';
import { Spin, Tooltip, Input } from 'antd';
import {
LeftOutlined,
RightOutlined,
PlusCircleOutlined,
MinusCircleOutlined,
FullscreenExitOutlined,
FullscreenOutlined,
CloseCircleOutlined,
ExclamationCircleOutlined,
RotateLeftOutlined,
RotateRightOutlined,
UnorderedListOutlined,
} from '@ant-design/icons';
import './index.less';
import { Document, Page, pdfjs } from 'react-pdf';
import pdfjsWorker from 'react-pdf/dist/esm/pdf.worker.entry';
pdfjs.GlobalWorkerOptions.workerSrc = pdfjsWorker;
const PDFView = ({
file,
parentDom,
onClose,
}: {
file?: string | null;
parentDom?: HTMLDivElement | null;
onClose?: () => void;
}) => {
const defaultWidth = 600;
const pageDiv = useRef(null);
const [numPages, setNumPages] = useState(0);
const [pageNumber, setPageNumber] = useState(1);
const [pageWidth, setPageWidth] = useState(defaultWidth);
const [fullscreen, setFullscreen] = useState(false);
const [rotation, setRotation] = useState(0);
const [showThumbnails, setShowThumbnails] = useState(false);
const [visiblePages, setVisiblePages] = useState([1]); // 控制可见页面
const parent = parentDom || document.body;
// 加载 PDF 元信息，不渲染全部页面
const onDocumentLoadSuccess = useCallback(({ numPages }: { numPages: number }) => {
setNumPages(numPages);
}, []);
const lastPage = () => pageNumber > 1 && setPageNumber(pageNumber - 1);
const nextPage = () => pageNumber < numPages && setPageNumber(pageNumber + 1);
const onPageNumberChange = (e: { target: { value: string } }) => {
let value = Math.max(1, Math.min(numPages, Number(e.target.value) || 1));
setPageNumber(value);
setVisiblePages([value]); // 只加载当前页
};
const pageZoomIn = () => setPageWidth(pageWidth * 1.2);
const pageZoomOut = () => pageWidth > defaultWidth && setPageWidth(pageWidth * 0.8);
const pageFullscreen = () => {
setPageWidth(fullscreen ? defaultWidth : parent.offsetWidth - 50);
setFullscreen(!fullscreen);
};
const rotateLeft = () => setRotation((prev) => (prev - 90) % 360);
const rotateRight = () => setRotation((prev) => (prev + 90) % 360);
const toggleThumbnails = () => setShowThumbnails(!showThumbnails);
// 动态更新可见页面
useEffect(() => {
if (!showThumbnails) {
setVisiblePages([pageNumber]);
} else {
// 缩略图模式下限制加载数量，避免卡顿
const start = Math.max(1, pageNumber - 2);
const end = Math.min(numPages, pageNumber + 2);
setVisiblePages(Array.from({ length: end - start + 1 }, (_, i) => start + i));
}
}, [pageNumber, showThumbnails, numPages]);
useEffect(() => setPageNumber(1), [file]);
useEffect(() => {
if( pageDiv.current){
(pageDiv.current.scrollTop = 0)
}
}, [pageNumber]);
const renderContent=()=>(
}
loading={
{' '}
/ {numPages}
{fullscreen ?
{onClose && (
)}
优化后的样式 (index.less)
.view {
position: absolute;
top: 0;
right: 0;
bottom: 0;
left: 0;
z-index: 999;
}
.viewContent {
position: relative;
width: 100%;
height: 100%;
}
.pageMain {
display: flex;
justify-content: center;
width: 100%;
height: 100%;
overflow: auto;
background: #444;
}
.pageContainer {
width: max-content;
max-width: 100%;
margin: 25px 0;
background: #fff;
box-shadow: rgba(0, 0, 0, 0.2) 0px 2px 4px 0px;
// :global {
// .react-pdf__Page__textContent { display: none; }
// }
}
.pageBar {
position: absolute;
bottom: 35px;
width: 100%;
text-align: center;
}
.pageTool {
display: inline-block;
padding: 8px 15px;
color: white;
background: rgba(66, 66, 66, 0.5);
border-radius: 15px;
box-shadow: rgba(0, 0, 0, 0.2) 0px 2px 4px 0px;
span {
margin: 0 5px;
padding: 5px;
&:hover { background: #333; }
}
input {
display: inline-block;
width: 50px;
height: 24px;
margin-right: 10px;
text-align: center;
}
input::-webkit-outer-spin-button,
input::-webkit-inner-spin-button { -webkit-appearance: none; }
input[type='number'] { -moz-appearance: textfield; }
}
.thumbnailContainer {
display: flex;
flex-wrap: wrap;
justify-content: center;
gap: 20px;
padding: 20px;
}
.thumbnail {
cursor: pointer;
text-align: center;
background: #fff;
padding: 10px;
border-radius: 5px;
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
&:hover { box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2); }
}
.thumbnailPlaceholder {
width: 150px;
height: 200px;
display: flex;
align-items: center;
justify-content: center;
background: #f0f0f0;
color: #666;
}
1. 组件设计：灵活与可控
- 输入参数：
- file：PDF 文件的 URL 或数据。
- parentDom：渲染的目标容器，默认 document.body。
- onClose：关闭回调。
- 渲染方式：用 createPortal 将组件挂载到指定 DOM，实现模态效果。
2. 状态管理：交互的核心
- numPages 和 pageNumber：控制总页数和当前页。
- pageWidth：动态调整页面宽度，默认 600px。
- fullscreen：切换全屏状态。
3. 功能实现：用户体验的加分项
- 翻页：lastPage 和 nextPage 控制前后翻页，Input 支持手动输入页码。
- 缩放：pageZoomIn（放大 1.2 倍）、pageZoomOut（缩小 0.8 倍，限制最小值）。
- 全屏：pageFullscreen 切换宽度至容器大小。
- 滚动重置：页面切换时自动滚动到顶部。
4. UI 与样式：美观与实用并存
- 布局：深色背景、白底页面、居中展示。
- 工具栏：悬浮底部，包含翻页、缩放、全屏按钮，带 Tooltip 提示。
- 加载与错误：用 Spin 和图标提示，提升用户感知。
Embed vs 自定义：谁更胜一筹？
我们用一个表格对比
| 特性 | PDFView | |
|---|---|---|
| 实现方式 | 原生 HTML 标签 | React 组件，基于 react-pdf |
| 样式控制 | 有限（仅宽高） | 完全自定义（背景、工具栏、页面样式） |
| 交互功能 | 内置工具栏（可隐藏但不灵活） | 自定义翻页、缩放、全屏，手动控制页码 |
| 加载提示 | 无 | 支持加载和错误提示 |
| 全屏支持 | 依赖浏览器 | 一键切换全屏 |
| 代码维护性 | 无需维护 | React 组件化，易扩展 |
| 依赖性 | 无需额外库 | 依赖 react-pdf 和 pdfjs-dist |
选择 PDFView 的理由
- 灵活性：自定义样式和交互，适配复杂需求。
- 用户体验：翻页、缩放、全屏一应俱全，加载和错误状态友好。
- 可维护性：组件化设计，易于集成和扩展。
使用场景：从 Demo 看效果
如何使用这个组件？
该组件已集成到 react-nexlif 开源库中。 具体文档可参考详情文档。你可以通过以下方式引入并使用：
示例代码
import React, { useState,useRef } from 'react';
import { PDFView } from 'react-nexlif';
import { Button, Modal } from 'antd';
const App: React.FC = () => {
const [fileUrl, setFileUrl] = useState(null);
const ref = useRef(null);
const [visible, setVisible] = useState(false);
const handleFileChange = (e: React.ChangeEvent) => {
const file = e.target.files?.[0];
if (file) {
setFileUrl(URL.createObjectURL(file))
};
};
return (
{fileUrl&& {
setFileUrl(null)
}}
/>}
);
};
export default App; 使用效果
- 上传大文件：加载 50 页 PDF，仅渲染当前页，响应迅速。
- 翻页与跳转：左右箭头或输入页码切换，滚动自动归顶。
- 旋转：点击旋转按钮，页面顺时针或逆时针调整。
- 缩略图：点击列表图标，显示所有页面预览，点击跳转。
- 缩放与全屏：放大缩小页面，或一键铺满屏幕。
性能对比：优化前后
| 特性 | 优化前 | 优化后 |
|---|---|---|
| 30 页加载 | 卡顿数秒 | 秒开，仅加载当前页 |
| 内存占用 | 高（全量解析） | 低（按需加载） |
| 缩略图性能 | 全渲染，易卡 | 部分渲染，轻量快捷 |
| 响应速度 | 慢 | 快 |
优化后，30 页 PDF 从“卡到怀疑人生”变成了“快如闪电”，用户体验和性能双双起飞！
技术亮点：为什么它这么强？
- 性能飞跃：
- 分页加载避免内存爆炸，大文件也能轻松应对。
- 动态加载逻辑清晰，体验流畅。
- 功能升级：
- 页面旋转解决方向问题，实用性拉满。
- 多页预览提供全局视角，操作更直观。
- 用户体验：
- 缩略图模式与单页模式无缝切换。
- 工具栏新增图标，交互更友好。
总结：你的 PDF 预览“性能王”
优化后的 PDFView 堪称 PDF 预览的“性能王”，30 页大文件不卡，加载快如闪电。通过按需加载和轻量化渲染，它解决了卡顿难题；加上旋转和多页预览，功能也更强大。试着把它丢进你的项目，上传个大 PDF 测试一下，感受性能飞跃的快感吧！有其他需求或优化思路？欢迎留言，我们一起把它打磨得更牛！
关键词：React PDF 预览、大文件优化、按需加载、性能提升、前端 PDF 处理。