@mxmweb/fviewer 1.5.4 → 1.5.6

package/README.md

@@ -1,591 +1,240 @@
 # @mxmweb/fviewer
 
-一个功能强大的文件查看器库，支持多种文件格式的解析和显示，包括PDF、图片、文本、Markdown等格式。
+> 一个功能强大的文件查看器库，支持多种文件格式的解析和显示，包括PDF、图片、文本、Markdown等格式
 
-## 安装与依赖
+[![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)
 
-本库为“易安装应用库”，仅外置最小运行时依赖。请在宿主项目中安装以下对等依赖（peerDependencies）：
+## ✨ 核心特性
+
+- ✅ **多格式支持**：支持 PDF、图片、文本、Markdown、HTML 等多种文件格式
+- ✅ **智能文件解析**：自动检测文件类型并调用相应的解析器
+- ✅ **完整的标注功能**：支持 PDF、Markdown、表格等多种标注类型
+- ✅ **动态主题系统**：支持运行时主题切换，所有样式可配置
+- ✅ **事件驱动架构**：通过 eventsEmit 统一处理所有交互事件
+- ✅ **TypeScript 支持**：完整的类型定义，提供良好的开发体验
+- ✅ **自定义组件**：支持自定义加载和错误组件
+
+## 📦 安装
 
 ```bash
 # 使用 pnpm（推荐）
-pnpm add @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
-
-# 或 npm
-npm i @mxmweb/fviewer \
-  react react-dom \
-  styled-components @mxmweb/zui @mxmweb/rtext \
-  pdfjs-dist
-```
+pnpm add @mxmweb/fviewer react react-dom styled-components @mxmweb/zui @mxmweb/rtext pdfjs-dist
 
-PDF.js 的 worker 需由宿主自行注册一次（任意应用初始化位置）：
+# 使用 npm
+npm install @mxmweb/fviewer react react-dom styled-components @mxmweb/zui @mxmweb/rtext pdfjs-dist
 
-```ts
-import * as pdfjsLib from 'pdfjs-dist';
+# 使用 yarn
+yarn add @mxmweb/fviewer react react-dom styled-components @mxmweb/zui @mxmweb/rtext pdfjs-dist
+```
 
-// 方式一：指向你静态资源中的 worker 文件
-pdfjsLib.GlobalWorkerOptions.workerSrc = '/worker/pdf.worker.min.js';
+### 必需依赖
+
+本库需要以下 peerDependencies：
 
-// 方式二：直接引入（需确保构建可访问该路径）
-// import 'pdfjs-dist/build/pdf.worker.min.js';
+```bash
+pnpm add react@>=18 react-dom@>=18 styled-components@^6.1.19 @mxmweb/zui@^1.* @mxmweb/rtext@^1.* pdfjs-dist@2.16.105
 ```
 
-> 说明：为降低包体积，`@mxmweb/rtext` 与 `pdfjs-dist` 均已外置；`react/react-dom/@mxmweb/zui/styled-components` 作为运行时依赖亦需由宿主提供。
+### PDF Worker 注册
 
-## 核心组件
+PDF.js 的 worker 需由宿主自行注册一次（任意应用初始化位置）：
 
-### StaticFileReader
+```typescript
+import { registerPDFWorker } from '@mxmweb/fviewer';
 
-静态文件阅读器组件，用于加载和显示本地或远程静态文件。
+// 注册PDF Worker
+registerPDFWorker('/worker/pdf.worker.min.js');
 
-#### Props接口
-
-- **fileUrl**: `string` - 文件URL地址（必需）
-- **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?, ErrorComponent? }` - 自定义组件（可选）
-- **className**: `string` - 自定义类名（可选）
-- **headerClass**: `string` - 头部类名（可选）
-- **contentClass**: `string` - 内容类名（可选）
-
-#### 调用实例
+// 或者手动注册
+import * as pdfjsLib from 'pdfjs-dist';
+pdfjsLib.GlobalWorkerOptions.workerSrc = '/worker/pdf.worker.min.js';
+```
 
-```tsx
-import { StaticFileReader } from '@mxmweb/fviewer';
+### 样式引入
 
-function App() {
-  const handleEvents = (name: string, data?: any) => {
-    switch (name) {
-      case 'file_loaded':
-        console.log('文件加载完成:', data);
-        break;
-      case 'page_changed':
-        console.log('页面切换:', data);
-        break;
-      case 'annotation_added':
-        console.log('添加标注:', data);
-        break;
-    }
-  };
+在项目入口文件中引入样式：
 
-  return (
-    <StaticFileReader
-      fileUrl="https://example.com/document.pdf"
-      fileName="示例文档.pdf"
-      fileType="pdf"
-      initialPage={1}
-      eventsEmit={handleEvents}
-      styles={{
-        mode: 'light',
-        theme: {
-          colors: {
-            primary: '#1890ff',
-            background: '#ffffff',
-            text: '#000000'
-          }
-        }
-      }}
-      tools={{
-        annotation: true,
-        download: true,
-        zoom: true,
-        navigation: true
-      }}
-    />
-  );
-}
+```typescript
+import '@mxmweb/fviewer/style.css';
 ```
 
-#### eventsEmit详细说明
-
-| 事件名 | 说明 | 数据格式 |
-| --- | ---- | --- |
-| `file_loaded` | 文件加载完成 | `{ fileName: string, fileType: string, totalPages?: number }` |
-| `page_changed` | 页面切换 | `{ currentPage: number, totalPages: number }` |
-| `annotation_added` | 添加标注 | `{ id: string, pageNumber: number, x: number, y: number, content: string }` |
-| `annotation_removed` | 删除标注 | `{ id: string }` |
-| `zoom_changed` | 缩放变化 | `{ scale: number }` |
-| `download_clicked` | 下载按钮点击 | `{ fileName: string }` |
-| `error_occurred` | 错误发生 | `{ error: string, details?: any }` |
-
-#### 技术栈
-
-- React 18 + TypeScript
-- Styled-components v6 主题样式
-- PDF.js 用于PDF文件解析
-- 响应式设计，支持移动端
-
-#### 其他
-
-- 支持多种文件格式：PDF、图片、文本、Markdown、HTML
-- 内置文件类型自动检测
-- 支持自定义主题和样式
-- 提供完整的标注功能
-- 支持文件下载和打印
-
-### GientechStreamReader
-
-流式文件阅读器组件，专门用于处理大文件的流式加载和分页显示。
-
-#### Props接口
-
-- **convertedFilePath**: `string` - 转换后的文件路径（必需）
-- **csrfToken**: `string` - CSRF令牌（可选）
-- **fileName**: `string` - 文件名（可选）
-- **fileType**: `string` - 文件类型（必需）
-- **initialPage**: `number` - 初始页码（可选）
-- **totalPages**: `number` - 总页数（可选）
-- **annotations**: `(Annotation | MDAnnotation | TableAnnotation)[]` - 标注数据数组（可选）
-- **userName**: `string` - 用户名（可选）
-- **userId**: `string` - 用户ID（可选）
-- **pageSize**: `number` - 页面大小（可选）
-- **streamApiUrl**: `string` - 流式API地址（可选）
-- **authorization**: `string` - 授权头（可选）
-- **eventsEmit**: `(name: string, data?: any, innerFn?: any) => void` - 事件回调函数（可选）
-- **tools**: `Partial<ToolsConfig>` - 工具配置（可选）
-- **styles**: `Styles` - 样式配置（可选）
-- **customComponents**: `{ LoadingComponent?, ErrorComponent? }` - 自定义组件（可选）
-- **className**: `string` - 自定义类名（可选）
-- **headerClass**: `string` - 头部类名（可选）
-- **contentClass**: `string` - 内容类名（可选）
-
-#### 调用实例
+## 🚀 快速开始
+
+### 基础用法
 
 ```tsx
-import { GientechStreamReader } from '@mxmweb/fviewer';
+import React from 'react';
+import { StaticFileReader } from '@mxmweb/fviewer';
+import '@mxmweb/fviewer/style.css';
 
 function App() {
-  const handleStreamEvents = (name: string, data?: any) => {
-    switch (name) {
-      case 'page_loaded':
-        console.log('页面加载完成:', data);
-        break;
-      case 'stream_error':
-        console.log('流式加载错误:', data);
-        break;
-      case 'cache_updated':
-        console.log('缓存更新:', data);
-        break;
-    }
+  const handleEvents = (eventName: string, data?: any) => {
+    console.log('Event:', eventName, data);
   };
 
   return (
-    <GientechStreamReader
-      convertedFilePath="/api/files/12345"
-      fileType="pdf"
-      fileName="大型文档.pdf"
-      totalPages={1000}
-      pageSize={10}
-      userName="张三"
-      userId="user123"
-      eventsEmit={handleStreamEvents}
-      tools={{
-        annotation: true,
-        navigation: true,
-        zoom: true
-      }}
-      styles={{
-        theme: {
-          colors: {
-            primary: '#52c41a',
-            background: '#fafafa'
+    <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>
   );
 }
-```
-
-#### eventsEmit详细说明
-
-| 事件名 | 说明 | 数据格式 |
-| --- | ---- | --- |
-| `page_loaded` | 页面加载完成 | `{ pageNo: number, data: ArrayBuffer, timestamp: number }` |
-| `stream_error` | 流式加载错误 | `{ error: string, pageNo?: number, retryCount: number }` |
-| `cache_updated` | 缓存更新 | `{ cacheKey: string, pages: number[], timestamp: number }` |
-| `page_requested` | 页面请求开始 | `{ pageNo: number, requestId: string }` |
-| `navigation_changed` | 导航变化 | `{ currentPage: number, totalPages: number, direction: 'next' \| 'prev' }` |
-| `user_action` | 用户操作 | `{ action: string, pageNo: number, timestamp: number }` |
 
-#### 技术栈
-
-- React 18 + TypeScript
-- Axios 用于HTTP请求
-- 智能分页缓存系统
-- 流式数据加载
-- 内存优化管理
-
-#### 其他
-
-- 支持超大文件的分页加载
-- 智能缓存策略，减少重复请求
-- 支持断点续传和错误重试
-- 内存使用优化，避免内存泄漏
-- 支持多种认证方式
-
-## 工具函数
-
-### parseFile
-
-通用文件解析函数，自动检测文件类型并调用相应的解析器。
-
-```tsx
-import { parseFile } from '@mxmweb/fviewer';
-
-const result = await parseFile(fileData, {
-  fileName: 'document.pdf',
-  fileType: 'pdf'
-});
+export default App;
 ```
 
-### parsePdfFile
+## 🔗 链接
 
-专门用于解析PDF文件的函数。
+- **NPM**: <https://www.npmjs.com/package/@mxmweb/fviewer>
+- **GitHub**: <https://github.com/your-org/fviewer>
 
-```tsx
-import { parsePdfFile } from '@mxmweb/fviewer';
+## 📚 API 文档
 
-const pdfResult = await parsePdfFile(pdfArrayBuffer, {
-  fileName: 'document.pdf'
-});
-```
-
-### parseImageFile
-
-图片文件解析函数。
-
-```tsx
-import { parseImageFile } from '@mxmweb/fviewer';
-
-const imageResult = await parseImageFile(imageBlob, {
-  fileName: 'image.jpg'
-});
-```
-
-### parseTextFile
-
-文本文件解析函数。
-
-```tsx
-import { parseTextFile } from '@mxmweb/fviewer';
-
-const textResult = await parseTextFile(textContent, {
-  fileName: 'document.txt'
-});
-```
-
-### parseMarkdownFile
-
-Markdown文件解析函数。
+> 📖 完整 API 文档请查看：[doc_assets/接口/](./doc_assets/接口/)
 
-```tsx
-import { parseMarkdownFile } from '@mxmweb/fviewer';
+- **接口文档**: [Fviewer API](./doc_assets/接口/Fviewer.md)、[StaticFileReader API](./doc_assets/接口/StaticFileReader.md)
+- **更新说明**: [CHANGELOG](./doc_assets/更新说明/CHANGELOG.md)
+- **演示说明**: [演示文档](./doc_assets/演示/index.md)
 
-const mdResult = await parseMarkdownFile(markdownContent, {
-  fileName: 'readme.md'
-});
-```
+### 核心组件（Core Components）
 
-### detectFileType
+#### Fviewer
 
-文件类型检测函数。
+核心文件查看器组件，提供基础的文件显示和交互能力。
 
-```tsx
-import { detectFileType } from '@mxmweb/fviewer';
-
-const fileType = detectFileType('document.pdf', 'pdf');
-// 返回: 'pdf'
-```
-
-### registerPDFWorker
-
-PDF Worker注册函数。
-
-```tsx
-import { registerPDFWorker } from '@mxmweb/fviewer';
-
-// 注册PDF Worker
-registerPDFWorker('/worker/pdf.worker.min.js');
-```
-
-### isPDFWorkerRegistered
-
-检查PDF Worker是否已注册的函数。
-
-```tsx
-import { isPDFWorkerRegistered } from '@mxmweb/fviewer';
-
-const isRegistered = isPDFWorkerRegistered();
-console.log('PDF Worker已注册:', isRegistered);
-```
-
-### getPDFWorkerPath
-
-获取当前PDF Worker路径的函数。
-
-```tsx
-import { getPDFWorkerPath } from '@mxmweb/fviewer';
-
-const workerPath = getPDFWorkerPath();
-console.log('当前PDF Worker路径:', workerPath);
-```
-
-## 类型定义
-
-### StaticFileReaderProps
-
-静态文件阅读器组件的属性接口。
-
-```tsx
-interface StaticFileReaderProps {
-  // 文件相关
-  fileUrl: string;
-  fileType?: string;
-  fileName?: string;
-  token?: string;
-  initialPage?: number;
-  annotations?: (Annotation | MDAnnotation | TableAnnotation)[];
-  // 直接数据传递
-  data?: any;
-  // 事件回调
+```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?: {
-    LoadingComponent?: React.ComponentType<{
-      status: string;
-      theme: AppTheme;
-    }>;
-    ErrorComponent?: React.ComponentType<{
-      error: string;
-      theme: AppTheme;
-    }>;
-  };
-  // 自定义类名
+  customComponents?: CustomizeComponents;
   className?: string;
-  headerClass?: string;
   contentClass?: string;
 }
 ```
 
-### GientechStreamReaderProps
+#### StaticFileReader
 
-流式文件阅读器组件的属性接口。
+静态文件阅读器组件，用于加载和显示本地或远程静态文件。
 
-```tsx
-interface GientechStreamReaderProps {
-  // 文件相关
-  convertedFilePath: string;
-  csrfToken?: string;
+```typescript
+interface StaticFileReaderProps {
+  fileUrl?: string;
+  fileType?: string;
   fileName?: string;
-  fileType: string;
+  token?: string;
   initialPage?: number;
-  totalPages?: number;
   annotations?: (Annotation | MDAnnotation | TableAnnotation)[];
-  // 用户信息
-  userName?: string;
-  userId?: string;
-  pageSize?: number;
-  // API配置
-  streamApiUrl?: string;
-  authorization?: string;
-  // 事件回调
+  data?: any;
   eventsEmit?: (name: string, data?: any, innerFn?: any) => void;
-  // 工具配置
-  tools?: Partial<ToolsConfig>;
-  // 样式配置
-  styles?: Styles;
-  // 自定义组件
+  styles?: {
+    theme?: AppTheme;
+    mode?: 'light' | 'dark';
+  };
+  tools?: ToolsConfig;
   customComponents?: {
-    LoadingComponent?: React.ComponentType<{
-      status: string;
-      theme: AppTheme;
-    }>;
-    ErrorComponent?: React.ComponentType<{
-      error: string;
-      theme: AppTheme;
-    }>;
+    LoadingComponent?: React.ComponentType<{ status: string; theme: AppTheme }>;
+    ErrorComponent?: React.ComponentType<{ error: string; theme: AppTheme }>;
   };
-  // 自定义类名
   className?: string;
   headerClass?: string;
   contentClass?: string;
 }
 ```
 
-### PdfRenderProps
-
-PDF渲染组件的属性接口。
-
-```tsx
-interface PdfRenderProps {
-  data: ArrayBuffer | string;
-  pageNumber?: number;
-  scale?: number;
-  annotations?: Annotation[];
-  onPageChange?: (pageNumber: number) => void;
-  onScaleChange?: (scale: number) => void;
-}
-```
-
-### Annotation
-
-PDF标注数据接口。
-
-```tsx
-interface Annotation {
-  id: string;
-  pageNumber: number;
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-  content?: string;
-  color?: string;
-}
-```
-
-### MDAnnotation
+### 工具函数
 
-Markdown标注数据接口。
+- `parseFile` - 通用文件解析函数
+- `parsePdfFile` - PDF文件解析函数
+- `parseImageFile` - 图片文件解析函数
+- `parseTextFile` - 文本文件解析函数
+- `parseMarkdownFile` - Markdown文件解析函数
+- `detectFileType` - 文件类型检测函数
+- `registerPDFWorker` - PDF Worker注册函数
+- `isPDFWorkerRegistered` - 检查PDF Worker是否已注册
+- `getPDFWorkerPath` - 获取当前PDF Worker路径
 
-```tsx
-interface MDAnnotation {
-  id: string;
-  start: number;
-  end: number;
-  content?: string;
-  color?: string;
-}
-```
+## 🛠️ 技术栈
 
-### TableAnnotation
+- **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 解析库
 
-表格标注数据接口。
+## 📁 项目结构
 
-```tsx
-interface TableAnnotation {
-  id: string;
-  offsets: [number, number][];
-  content?: string;
-  color?: string;
-}
+```text
+src/
+├── lib_enter.ts              # 库入口，导出所有公共 API
+├── style.css                 # 样式文件
+├── core/                     # 核心组件
+│   ├── Fviewer.tsx           # Fviewer 核心组件
+│   ├── types.ts              # 类型定义
+│   ├── PdfRender.tsx         # PDF 渲染组件
+│   └── utils/                # 工具函数
+│       └── fileParser.ts     # 文件解析工具
+└── adopters/                 # 业务扩展组件
+    └── StaticFileReader.tsx  # 静态文件阅读器
 ```
 
-### ToolsConfig
-
-工具配置接口。
-
-```tsx
-interface ToolsConfig {
-  annotation?: boolean;    // 标注功能
-  download?: boolean;      // 下载功能
-  zoom?: boolean;         // 缩放功能
-  close?: boolean;        // 关闭功能
-  navigation?: boolean;   // 导航功能
-  rotate?: boolean;       // 旋转功能（主要用于图片）
-}
-```
+## 🎯 使用场景
 
-### AppTheme
+- 文档预览系统
+- 文件管理系统
+- 在线文档阅读器
+- 知识库文档展示
+- 文件标注和批注系统
 
-应用主题接口。
+## 📝 示例
 
-```tsx
-interface AppTheme {
-  colors: {
-    primary: string;
-    secondary: string;
-    success: string;
-    warning: string;
-    error: string;
-    info: string;
-    background: string;
-    text: string;
-    border: string;
-    disabled: string;
-    disabledBackground: string;
-    disabledText: string;
-    [key: string]: any;
-  };
-  space: {
-    sidebar: string;
-    size: string;
-    radius: string;
-    padding: string;
-    margin: string;
-    shadow: string;
-    lineHeight: string;
-    [key: string]: any;
-  };
-  [key: string]: any;
-}
-```
+查看 `src/examples/` 目录获取更多完整示例：
 
-### Styles
+- **基础用法** - 简单的文件预览
+- **高级用法** - 包含标注、主题定制等完整功能
 
-样式配置接口，来自 @mxmweb/zui 包。
+## 📄 许可证
 
-```tsx
-import { Styles } from '@mxmweb/zui';
+MIT License
 
-// Styles 是一个通用的样式配置接口
-// 用于配置组件的主题和样式
-```
+## 👥 作者
 
-### ParseResult
+- **hanfeng_Zhang**
 
-文件解析结果接口。
+---
 
-```tsx
-interface ParseResult {
-  type: FileType;
-  content: any;
-  fileName?: string;
-  fileType?: string;
-  totalPages?: number;
-  error?: string;
-}
-```
-
-### ParseOptions
-
-文件解析选项接口。
-
-```tsx
-interface ParseOptions {
-  fileName?: string;
-  fileType?: string;
-  token?: string;
-}
-```
-
-### FileType
-
-文件类型枚举。
-
-```tsx
-type FileType = 'pdf' | 'image' | 'text' | 'markdown' | 'markdown_table' | 'html' | 'unknown';
-```
+⭐ 如果这个项目对你有帮助，请给它一个 Star！