react-doc-viewer 安装与使用教程：三步在 React 中实现文件在线预览

react-doc-viewer 安装与使用教程：三步在 React 中实现文件在线预览

【免费下载链接】react-doc-viewerFile viewer for React.项目地址: https://gitcode.com/gh_mirrors/re/react-doc-viewer

@cyntler/react-doc-viewer 是一个面向 React 17+ 的文件预览组件。传入一个文件地址数组，就能在浏览器里展示 PDF、Word、Excel、图片、视频等 20 余种格式，用户无需下载即可查看。远程 URL 与本地上传文件走的是同一个documents参数。

🚧 引入 react-doc-viewer 之前的麻烦

自己写预览，每种格式成本都不同：PDF 要自己处理分页、缩放与画布渲染；图片、文本要各写一套分支；MS Office 文件浏览器无法原生渲染，只能提示用户下载，或自己接入 iframe 服务。

📦 三步跑通一个预览页

先安装，再引入必要的样式，否则 PDF 渲染会出问题：

npm i @cyntler/react-doc-viewer

import DocViewer, { DocViewerRenderers } from "@cyntler/react-doc-viewer"; import "@cyntler/react-doc-viewer/dist/index.css"; const App = () => { const docs = [ { uri: "https://example.com/a.pdf" }, // 远程地址 { uri: require("./exampleFiles/pdf-file.pdf") }, // 本地文件 ]; return <DocViewer documents={docs} pluginRenderers={DocViewerRenderers} />; };

三步：安装 → 引入 css → 传入 documents 与 pluginRenderers。传完整的DocViewerRenderers会启用全部内置渲染器；只用到少数格式时，可单独导入并传[PDFRenderer, PNGRenderer]。

🗺️ 功能地图：四个核心能力

• 多格式渲染：documents数组（uri + 可选 fileName）覆盖 pdf、docx、xlsx、mp4、csv、tiff 等 20 余种格式，fileName 显示在顶部栏。
• 上传文件预览：把 input 选中的文件经URL.createObjectURL(file)转成 blob 地址，再作为 uri 传入即可。
• 展示控制：initialActiveDocument指定初始文档；1.11.0 起用activeDocument+onDocumentChange组合把切换权收归外部；1.13.0 起 ref 提供next()/prev()，可自接翻页按钮。
• 主题与多语言：theme参数控制主色、辅助色与文字颜色；language切换界面文案，支持 15 种语言。

🔧 实战细节：自定义请求与自定义渲染器

两个常见需求值得展开。其一是自定义请求：库默认用 HEAD 请求探测文件类型，地址若是 AWS 预签名 URL，改用prefetchMethod="GET"，并用requestHeaders附加鉴权头。其二是自定义渲染器：不想走内置逻辑的格式，写个组件并声明fileTypes与weight：

const MyRenderer: DocRenderer = ({ mainState: { currentDocument } }) => currentDocument ? <iframe src={currentDocument.fileData} /> : null; MyRenderer.fileTypes = ["svg"]; MyRenderer.weight = 1; <DocViewer pluginRenderers={[MyRenderer, ...DocViewerRenderers]} />;

若要完全接管文件加载，可给组件附加fileLoader回调，加载完成后调用fileLoaderComplete()关闭 loading 状态。

⚠️ 使用时的三个避坑点

1. Office 格式仅支持公网 URL：doc/docx/xls/xlsx/ppt/pptx/odt 走微软在线转换服务，私有或内网文件打不开。
2. 高度默认随内容伸缩：高度随文件展开收缩、宽度撑满父容器，布局跳动时给外层容器固定高度。
3. 已停止维护：作者在 README 中声明停止开发该库，功能稳定，但不要期待快速修复。

👥 适合谁用

适合后台管理、知识库、商品资料展示等"浏览器里打开"的场景；若需预览 Office 私有文档或离线/内网部署，请另选方案。完整参数见 README.md，各渲染器源码在 src/renderers/。

收尾

一个参数覆盖 20 余种格式，接入现有页面成本低；Office 格式的公网依赖与维护停止这两个限制，用前务必确认。下一步：把快速上手里的最小示例拷进你的项目，传一个 PDF 加一张图片，先跑通再谈定制。

【免费下载链接】react-doc-viewerFile viewer for React.项目地址: https://gitcode.com/gh_mirrors/re/react-doc-viewer