# @mxmweb/fviewer

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

**说明**：在业务项目中请通过 npm 安装 **`@mxmweb/fviewer`**（如 `pnpm add @mxmweb/fviewer`）。若你在公开信息中看到源码目录带有 `private: true`，仅表示组织内的发版/workspace 配置，**不影响**使用已发布到 npm 的版本。

[![npm version](https://img.shields.io/npm/v/@mxmweb/fviewer.svg)](https://www.npmjs.com/package/@mxmweb/fviewer)
[![npm downloads](https://img.shields.io/npm/dm/@mxmweb/fviewer.svg)](https://www.npmjs.com/package/@mxmweb/fviewer)
[![License](https://img.shields.io/npm/l/@mxmweb/fviewer.svg)](https://github.com/your-org/fviewer/blob/main/LICENSE)

## ✨ 核心特性

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

## 📦 安装

```bash
# 使用 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：

```bash
pnpm add react@>=18 react-dom@>=18 styled-components@^6.1.19 @mxmweb/zui@^1.* @mxmweb/rtext@^1.* pdfjs-dist@2.16.105
```

### PDF Worker 注册

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

```typescript
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';
```

### 样式引入

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

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

## 🚀 快速开始

### 基础用法

```tsx
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/接口/](./doc_assets/接口/)

- **接口文档**: [Fviewer API](./doc_assets/接口/Fviewer.md)、[StaticFileReader API](./doc_assets/接口/StaticFileReader.md)
- **更新说明**: [CHANGELOG](./doc_assets/更新说明/CHANGELOG.md)
- **演示说明**: [演示文档](./doc_assets/演示/index.md)

### 核心组件（Core Components）

#### Fviewer

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

```typescript
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

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

```typescript
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 解析库

## 📁 项目结构

```text
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！