本文介绍如何通过自定义 onpassword 回调函数，在 react-pdf 中稳定、可控地加载密码保护 pdf，避免原生弹窗反复触发，并提供用户友好的密码输入、错误重试与失败降级体验。
本文介绍如何通过自定义 onpassword 回调函数，在 react-pdf 中稳定、可控地加载密码保护 pdf，避免原生弹窗反复触发，并提供用户友好的密码输入、错误重试与失败降级体验。
在使用 react-pdf 渲染受密码保护的 PDF 文件时，若未显式配置密码处理逻辑，库会默认调用内置的简单 prompt 弹窗，且在密码错误时重复触发——这不仅破坏用户体验，还可能导致无限循环或状态混乱。根本解决方式是完全接管密码验证流程，通过自定义 onPassword 函数实现精细化控制。
onPassword 接收两个参数：callback（用于向 PDF 解析器提交密码）和 reason（标识触发原因）。reason 值为 1 表示首次请求密码（文件受保护），2 表示密码错误需重试，其他值可忽略。我们据此设计分层提示逻辑：
import { Document, Page } from 'react-pdf';
import { useState } from 'react';
const PDFViewer = () => {
const [numPages, setNumPages] = useState<number | null>(null);
const [showDocument, setShowDocument] = useState(true);
const onDocumentLoadSuccess = ({ _pdfInfo }: any) => {
setNumPages(_pdfInfo.numPages);
};
const onPassword = (callback: (password: string) => void, reason: number) => {
const callbackProxy = (password: string | null) => {
if (password === null) {
// 用户点击“取消”：主动卸载组件，防止后续无效重试
setShowDocument(false);
return;
}
callback(password); // 将密码交由 PDF.js 内部验证
};
switch (reason) {
case 1:
const firstPassword = prompt('请输入打开此 PDF 的密码：');
callbackProxy(firstPassword);
break;
case 2:
const retryPassword = prompt('密码错误，请重新输入：');
callbackProxy(retryPassword);
break;
default:
callbackProxy(null);
}
};
return (
!showDocument ? (
<div className="pdf-error-state">
<p>❌ 无法加载受保护的 PDF 文件。</p>
<button
onClick={() => setShowDocument(true)}
className="retry-btn"
>
重新加载并输入密码
</button>
</div>
) : (
<Document
file="./sampleProtectedFile.pdf"
onLoadSuccess={onDocumentLoadSuccess}
onPassword={onPassword}
loading={<div>正在加载 PDF...</div>}
error={<div>加载失败，请检查文件路径或网络连接。</div>}
>
{Array.from(new Array(numPages), (_, i) => (
<Page
key={`page_${i + 1}`}
pageNumber={i + 1}
renderTextLayer={false}
renderAnnotationLayer={false}
/>
))}
</Document>
)
);
};
export default PDFViewer;✅ 关键实践建议：
- 避免原生 prompt 硬编码：生产环境应替换为模态框（如 Material UI Dialog 或 Ant Design Modal），支持样式定制、键盘交互（Enter 提交/Escape 关闭）及无障碍访问；
- 增加防抖与重试限制：可在 case 2 分支中加入最大重试次数（如 3 次），超限后显示明确错误信息并禁用重试按钮；
- 密码安全提醒：前端密码输入不加密，仅用于 PDF 解密；敏感场景应确保 PDF 已在服务端完成权限校验，前端不暴露原始文件链接；
- 服务端预检（进阶）：可通过 API 先请求 PDF 元信息（如是否加密、加密类型），再决定是否启用密码流程，提升首屏响应体验。
通过以上方案，你不仅能彻底消除烦人的重复弹窗，还能将密码交互深度融入应用 UI 体系，显著提升专业度与用户信任感。
