React Doc Viewer 中文安装配置完整指南

项目概述

React Doc Viewer 是一个专为 React 应用设计的文件查看器库，支持多种文档格式的在线预览。该项目基于 React 17+ 开发，提供了丰富的文件格式支持和灵活的定制选项。

支持的文件格式

文件格式	MIME 类型	备注
PDF	application/pdf	完整支持
PNG	image/png	完整支持
JPG/JPEG	image/jpeg	完整支持
GIF	image/gif	完整支持
BMP	image/bmp	完整支持
CSV	text/csv	完整支持
TXT	text/plain	完整支持
DOC/DOCX	application/msword	仅支持公开URL
XLS/XLSX	application/vnd.ms-excel	仅支持公开URL
PPT/PPTX	application/vnd.ms-powerpoint	仅支持公开URL
HTML	text/html	完整支持
TIFF	image/tiff	完整支持
WEBP	image/webp	完整支持
MP4	video/mp4	完整支持

环境要求

在开始安装之前，请确保您的开发环境满足以下要求：

• Node.js 16.0 或更高版本
• npm 或 yarn 包管理器
• React 17.0 或更高版本
• TypeScript（可选，推荐使用）

安装步骤

1. 创建新的 React 项目

如果您还没有 React 项目，请先创建一个：

npx create-react-app my-doc-viewer-app --template typescript
cd my-doc-viewer-app

2. 安装 React Doc Viewer

使用 npm 或 yarn 安装核心库：

npm install @cyntler/react-doc-viewer
# 或者
yarn add @cyntler/react-doc-viewer

3. 基础配置

在您的 React 应用中引入必要的样式文件：

// 在 App.tsx 或主入口文件中添加
import "@cyntler/react-doc-viewer/dist/index.css";

基本使用示例

最简单的集成方式

import React from 'react';
import DocViewer, { DocViewerRenderers } from '@cyntler/react-doc-viewer';
import '@cyntler/react-doc-viewer/dist/index.css';

function App() {
  const documents = [
    { uri: "https://example.com/sample.pdf" },  // 远程文件
    { uri: require("./documents/local-file.pdf") }  // 本地文件
  ];

  return (
    <div style={{ height: '100vh' }}>
      <DocViewer 
        documents={documents} 
        pluginRenderers={DocViewerRenderers}
      />
    </div>
  );
}

export default App;

PDF文档预览示例

处理上传的文件

React Doc Viewer 支持直接显示用户上传的文件：

import React, { useState } from 'react';
import DocViewer, { DocViewerRenderers } from '@cyntler/react-doc-viewer';

const FileUploadViewer = () => {
  const [uploadedFiles, setUploadedFiles] = useState<any[]>([]);

  const handleFileUpload = (event: React.ChangeEvent<HTMLInputElement>) => {
    const files = event.target.files;
    if (files && files.length > 0) {
      const fileArray = Array.from(files).map(file => ({
        uri: URL.createObjectURL(file),
        fileName: file.name,
        fileType: file.type
      }));
      setUploadedFiles(fileArray);
    }
  };

  return (
    <div>
      <input
        type="file"
        multiple
        accept=".pdf,.doc,.docx,.xls,.xlsx,.jpg,.png"
        onChange={handleFileUpload}
      />
      {uploadedFiles.length > 0 && (
        <DocViewer
          documents={uploadedFiles}
          pluginRenderers={DocViewerRenderers}
        />
      )}
    </div>
  );
};

高级配置选项

自定义主题

您可以通过主题配置来自定义查看器的外观：

<DocViewer
  documents={documents}
  pluginRenderers={DocViewerRenderers}
  theme={{
    primary: "#5296d8",
    secondary: "#ffffff",
    tertiary: "#5296d899",
    textPrimary: "#ffffff",
    textSecondary: "#5296d8",
    textTertiary: "#00000099",
    disableThemeScrollbar: false,
  }}
/>

多语言支持

React Doc Viewer 支持国际化，目前内置多种语言：

<DocViewer
  documents={documents}
  pluginRenderers={DocViewerRenderers}
  language="zh"  // 支持 en, pl, de, fr, es, it, ja, ru, tr 等
/>

高级配置选项

<DocViewer
  documents={documents}
  pluginRenderers={DocViewerRenderers}
  config={{
    header: {
      disableHeader: false,
      disableFileName: false,
      retainURLParams: false,
    },
    csvDelimiter: ",",
    pdfZoom: {
      defaultZoom: 1.0,
      zoomJump: 0.1,
    },
    pdfVerticalScrollByDefault: false,
    loadingRenderer: {
      showLoadingTimeout: 500,
    }
  }}
/>

自定义渲染器开发

创建自定义文件渲染器

如果您需要支持特殊的文件格式，可以创建自定义渲染器：

import React from 'react';

const CustomEPSRenderer = ({ mainState }) => {
  if (!mainState.currentDocument) return null;

  return (
    <div style={{ padding: '20px', textAlign: 'center' }}>
      <h3>EPS 文件预览</h3>
      <p>当前文件: {mainState.currentDocument.fileName}</p>
      <div style={{ background: '#f5f5f5', padding: '20px', borderRadius: '8px' }}>
        <p>EPS 文件需要专门的软件查看，建议下载后使用专业工具打开</p>
        <a 
          href={mainState.currentDocument.uri} 
          download
          style={{
            padding: '10px 20px',
            background: '#5296d8',
            color: 'white',
            textDecoration: 'none',
            borderRadius: '4px'
          }}
        >
          下载文件
        </a>
      </div>
    </div>
  );
};

CustomEPSRenderer.fileTypes = ['eps', 'application/postscript'];
CustomEPSRenderer.weight = 1;

export default CustomEPSRenderer;

使用自定义渲染器

import DocViewer, { DocViewerRenderers } from '@cyntler/react-doc-viewer';
import CustomEPSRenderer from './CustomEPSRenderer';

// 合并默认渲染器和自定义渲染器
const allRenderers = [...DocViewerRenderers, CustomEPSRenderer];

<DocViewer
  documents={documents}
  pluginRenderers={allRenderers}
/>

常见问题解决

1. 样式不生效

确保已正确导入 CSS 文件：

import "@cyntler/react-doc-viewer/dist/index.css";

2. 文件加载失败

检查文件URL是否可访问，对于远程文件确保CORS配置正确。

3. Office 文档无法预览

Office 文档需要公开可访问的URL，本地文件或需要认证的文件可能无法正常预览。

4. TypeScript 类型错误

确保正确导入类型定义，所有导出都有完整的TypeScript支持。

性能优化建议

1. 懒加载：对于大量文档，实现分页或虚拟滚动
2. 缓存策略：对已加载的文档实现本地缓存
3. 预加载：对可能查看的文档进行预加载
4. 错误边界：添加适当的错误处理机制

生产环境部署

构建优化

npm run build
# 或者
yarn build

Docker 部署示例

FROM node:16-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY build/ ./build/

EXPOSE 3000
CMD ["npx", "serve", "-s", "build", "-l", "3000"]

总结

React Doc Viewer 提供了一个强大且灵活的文件预览解决方案，支持多种文件格式和丰富的定制选项。通过本指南，您应该能够快速上手并在项目中集成这个优秀的库。

记住定期检查更新，以获取最新的功能改进和安全修复。如果您遇到任何问题，可以参考项目文档或查阅相关社区资源。