@mxmweb/fviewer

一个功能强大的文件查看器库，支持多种文件格式的解析和显示，包括PDF、图片、文本、Markdown等格式

✨ 核心特性

• ✅ 多格式支持：支持 PDF、图片、文本、Markdown、HTML 等多种文件格式
• ✅ 智能文件解析：自动检测文件类型并调用相应的解析器
• ✅ 完整的标注功能：支持 PDF、Markdown、表格等多种标注类型
• ✅ 动态主题系统：支持运行时主题切换，所有样式可配置
• ✅ 事件驱动架构：通过 eventsEmit 统一处理所有交互事件
• ✅ TypeScript 支持：完整的类型定义，提供良好的开发体验
• ✅ 自定义组件：支持自定义加载和错误组件

📦 安装

# 使用 pnpm（推荐）
pnpm add @mxmweb/fviewer react react-dom styled-components @mxmweb/zui @mxmweb/rtext pdfjs-dist

# 使用 npm
npm install @mxmweb/fviewer react react-dom styled-components @mxmweb/zui @mxmweb/rtext pdfjs-dist

# 使用 yarn
yarn add @mxmweb/fviewer react react-dom styled-components @mxmweb/zui @mxmweb/rtext pdfjs-dist

必需依赖

本库需要以下 peerDependencies：

pnpm add react@>=18 react-dom@>=18 styled-components@^6.1.19 @mxmweb/zui@^1.* @mxmweb/rtext@^1.* [email protected]

PDF Worker 注册

PDF.js 的 worker 需由宿主自行注册一次（任意应用初始化位置）：

import { registerPDFWorker } from '@mxmweb/fviewer';

// 注册PDF Worker
registerPDFWorker('/worker/pdf.worker.min.js');

// 或者手动注册
import * as pdfjsLib from 'pdfjs-dist';
pdfjsLib.GlobalWorkerOptions.workerSrc = '/worker/pdf.worker.min.js';

样式引入

在项目入口文件中引入样式：

import '@mxmweb/fviewer/style.css';

🚀 快速开始

基础用法

import React from 'react';
import { StaticFileReader } from '@mxmweb/fviewer';
import '@mxmweb/fviewer/style.css';

function App() {
  const handleEvents = (eventName: string, data?: any) => {
    console.log('Event:', eventName, data);
  };

  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <StaticFileReader
        fileUrl="https://example.com/document.pdf"
        fileName="示例文档.pdf"
        fileType="pdf"
        eventsEmit={handleEvents}
        styles={{
          mode: 'light',
          theme: {
            colors: {
              primary: '#1890ff',
              background: '#ffffff',
              text: '#000000'
            }
          }
        }}
        tools={{
          annotation: true,
          download: true,
          zoom: true,
          navigation: true
        }}
      />
    </div>
  );
}

export default App;

🔗 链接

• NPM: https://www.npmjs.com/package/@mxmweb/fviewer
• GitHub: https://github.com/your-org/fviewer

📚 API 文档

📖 完整 API 文档请查看：doc_assets/接口/

• 接口文档: Fviewer API、StaticFileReader API
• 更新说明: CHANGELOG
• 演示说明: 演示文档

核心组件（Core Components）

Fviewer

核心文件查看器组件，提供基础的文件显示和交互能力。

interface FviewerProps {
  data: FviewerData;
  annotationData?: (Annotation | MDAnnotation | TableAnnotation)[];
  totalPage?: number;
  currentPage?: number;
  scale?: number;
  initialZoom?: number;
  rotation?: number;
  setScale?: (scale: number) => void;
  eventsEmit?: (name: string, data?: any, innerFn?: any) => void;
  styles?: {
    theme?: AppTheme;
    mode?: 'light' | 'dark';
  };
  tools?: ToolsConfig;
  customComponents?: CustomizeComponents;
  className?: string;
  contentClass?: string;
}

StaticFileReader

静态文件阅读器组件，用于加载和显示本地或远程静态文件。

interface StaticFileReaderProps {
  fileUrl?: string;
  fileType?: string;
  fileName?: string;
  token?: string;
  initialPage?: number;
  annotations?: (Annotation | MDAnnotation | TableAnnotation)[];
  data?: any;
  eventsEmit?: (name: string, data?: any, innerFn?: any) => void;
  styles?: {
    theme?: AppTheme;
    mode?: 'light' | 'dark';
  };
  tools?: ToolsConfig;
  customComponents?: {
    LoadingComponent?: React.ComponentType<{ status: string; theme: AppTheme }>;
    ErrorComponent?: React.ComponentType<{ error: string; theme: AppTheme }>;
  };
  className?: string;
  headerClass?: string;
  contentClass?: string;
}

工具函数

• parseFile - 通用文件解析函数
• parsePdfFile - PDF文件解析函数
• parseImageFile - 图片文件解析函数
• parseTextFile - 文本文件解析函数
• parseMarkdownFile - Markdown文件解析函数
• detectFileType - 文件类型检测函数
• registerPDFWorker - PDF Worker注册函数
• isPDFWorkerRegistered - 检查PDF Worker是否已注册
• getPDFWorkerPath - 获取当前PDF Worker路径

🛠️ 技术栈

• React >=18 <20 - 前端框架
• TypeScript - 类型支持
• styled-components ^6.1.19 - CSS-in-JS 样式方案
• @mxmweb/zui ^1.* - UI 组件库
• @mxmweb/rtext ^1.* - 富文本组件库
• pdfjs-dist 2.16.105 - PDF 解析库

📁 项目结构

src/
├── lib_enter.ts              # 库入口，导出所有公共 API
├── style.css                 # 样式文件
├── core/                     # 核心组件
│   ├── Fviewer.tsx           # Fviewer 核心组件
│   ├── types.ts              # 类型定义
│   ├── PdfRender.tsx         # PDF 渲染组件
│   └── utils/                # 工具函数
│       └── fileParser.ts     # 文件解析工具
└── adopters/                 # 业务扩展组件
    └── StaticFileReader.tsx  # 静态文件阅读器

🎯 使用场景

• 文档预览系统
• 文件管理系统
• 在线文档阅读器
• 知识库文档展示
• 文件标注和批注系统

📝 示例

查看 src/examples/ 目录获取更多完整示例：

• 基础用法 - 简单的文件预览
• 高级用法 - 包含标注、主题定制等完整功能

📄 许可证

MIT License

👥 作者

• hanfeng_Zhang

⭐ 如果这个项目对你有帮助，请给它一个 Star！