@mxmweb/fviewer 1.1.16 → 1.2.16

package/README.md

@@ -1 +1,343 @@
-# 工具库架构初始化
+# FViewer - 文件查看器组件库
+
+## 项目概述
+
+FViewer 是一个基于 React 的文件查看器组件库，支持多种文件格式的预览和交互。项目采用分层架构设计，遵循 adopter_develop 规范，使用 HOC 模式封装核心组件。
+
+### 支持的文件格式
+- **PDF**: 支持分页查看、缩放、旋转
+- **Markdown**: 支持格式化渲染、无限滚动
+- **图片**: 支持常见图片格式（JPG、PNG、GIF等）
+- **文本**: 支持纯文本文件
+- **HTML**: 支持网页内容预览
+
+## 项目架构
+
+### 目录结构
+```
+apps/FViewer/
+├── src/
+│   ├── core/                 # 核心组件层
+│   │   ├── Fviewer.tsx      # 主查看器组件
+│   │   ├── PdfRender/       # PDF渲染组件
+│   │   ├── types.ts         # 类型定义
+│   │   └── utils/           # 工具函数
+│   ├── adopters/            # 业务适配层
+│   │   ├── GientechStreamReader.tsx  # Stream业务流适配器
+│   │   ├── StaticFileReader.tsx      # 静态文件适配器
+│   │   └── components/      # 适配器组件
+│   ├── StreamPreview.tsx    # Stream业务流测试组件
+│   └── main.tsx             # 应用入口
+├── package.json
+└── README.md
+```
+
+### 架构设计原则
+
+1. **分层架构**: 
+   - `/core/`: 核心UI组件，只负责渲染和基础交互
+   - `/adopters/`: 业务适配层，处理数据获取、缓存、业务逻辑
+
+2. **HOC模式**: 业务层通过高阶组件模式扩展核心组件功能
+
+3. **事件驱动**: 使用统一的 `eventsEmit` 机制进行组件间通信
+
+4. **主题化**: 支持动态主题配置，使用 styled-components 实现
+
+## 核心组件
+
+### Fviewer (核心查看器)
+
+**位置**: `src/core/Fviewer.tsx`
+
+**功能**: 文件类型检测、内容渲染、状态管理
+
+**接口**:
+```typescript
+interface FviewerProps {
+  data: FviewerData;           // 文件数据
+  annotationData?: Annotation[]; // 标注数据
+  totalPage?: number;          // 总页数
+  currentPage?: number;        // 当前页
+  scale?: number;              // 缩放比例
+  rotation?: number;           // 旋转角度
+  eventsEmit?: (name: string, data?: any) => void; // 事件回调
+  styles?: { theme?: AppTheme; mode?: 'light' | 'dark' }; // 样式配置
+  tools?: ToolsConfig;         // 工具配置
+  customComponents?: CustomizeComponents; // 自定义组件
+}
+```
+
+**事件**:
+- `markdown_scroll`: Markdown滚动事件
+- `pageChange`: 页面变化事件
+- `zoomChange`: 缩放变化事件
+- `annotationChange`: 标注变化事件
+
+### PdfRender (PDF渲染器)
+
+**位置**: `src/core/PdfRender/index.tsx`
+
+**功能**: PDF文档渲染、页面导航、缩放控制
+
+**特性**:
+- 支持分页PDF的页码映射
+- 基于PDF.js实现
+- 支持标注功能
+
+## 业务适配器
+
+### GientechStreamReader (Stream业务流适配器)
+
+**位置**: `src/adopters/GientechStreamReader.tsx`
+
+**功能**: 基于Stream API的文件读取器，支持分页获取和缓存
+
+**特性**:
+- **PDF支持**: 分页加载、智能缓存、页码映射
+- **Markdown支持**: 无限滚动、块级缓存、双向加载
+- **缓存机制**: 页面级和块级缓存，5分钟过期
+- **加载状态**: 初始加载、页面加载、无限滚动加载
+
+**接口**:
+```typescript
+interface GientechStreamReaderProps {
+  convertedFilePath: string;   // 文件路径
+  fileName?: string;           // 文件名
+  fileType: string;            // 文件类型
+  initialPage?: number;        // 初始页/块
+  totalPages?: number;         // 总页数/块数
+  pageSize?: number;           // 页面/块大小
+  streamApiUrl?: string;       // Stream API地址
+  authorization?: string;      // 认证信息
+  eventsEmit?: (name: string, data?: any) => void;
+  styles?: { theme?: AppTheme; mode?: 'light' | 'dark' };
+  tools?: ToolsConfig;
+  customComponents?: CustomizeComponents;
+}
+```
+
+**缓存策略**:
+- **PDF**: 缓存解析后的PDF文档对象，避免重复解析
+- **Markdown**: 缓存块级内容，支持向前/向后拼接
+
+**无限滚动**:
+- 向下滚动到底部80%时加载下一块
+- 向上滚动到顶部20%时加载上一块
+- 智能内容拼接，保持阅读连续性
+
+### StaticFileReader (静态文件适配器)
+
+**位置**: `src/adopters/StaticFileReader.tsx`
+
+**功能**: 静态文件读取器，支持本地文件预览
+
+## 使用示例
+
+### Stream业务流使用
+
+```tsx
+import GientechStreamReader from './adopters/GientechStreamReader';
+
+function App() {
+  const handleEvents = (name: string, data: any) => {
+    switch (name) {
+      case 'pageChange':
+        console.log('页面变化:', data);
+        break;
+      case 'markdown_scroll':
+        console.log('Markdown滚动:', data);
+        break;
+    }
+  };
+
+  return (
+    <GientechStreamReader
+      convertedFilePath="/path/to/file"
+      fileName="document.pdf"
+      fileType="pdf"
+      initialPage={1}
+      totalPages={100}
+      pageSize={5}
+      streamApiUrl="http://api.example.com/stream"
+      authorization="Bearer token"
+      eventsEmit={handleEvents}
+      styles={{
+        theme: {
+          colors: {
+            primary: '#007bff',
+            background: '#f8f9fa',
+            text: '#343a40'
+          }
+        }
+      }}
+      tools={{
+        zoom: true,
+        navigation: true,
+        close: true
+      }}
+    />
+  );
+}
+```
+
+### 自定义组件
+
+```tsx
+// 自定义加载组件
+const CustomLoading = ({ status, theme }) => (
+  <div style={{ color: theme.colors.primary }}>
+    自定义加载: {status}
+  </div>
+);
+
+// 自定义错误组件
+const CustomError = ({ error, theme }) => (
+  <div style={{ color: theme.colors.error }}>
+    自定义错误: {error}
+  </div>
+);
+
+<GientechStreamReader
+  // ... 其他属性
+  customComponents={{
+    LoadingComponent: CustomLoading,
+    ErrorComponent: CustomError
+  }}
+/>
+```
+
+## 开发指南
+
+### 添加新的文件类型支持
+
+1. **在Fviewer中添加类型检测**:
+```typescript
+// src/core/Fviewer.tsx
+const detectFileType = (data: any): FileType => {
+  // 添加新的类型检测逻辑
+  if (fileName.toLowerCase().endsWith('.newtype')) {
+    return 'newtype';
+  }
+  // ...
+};
+```
+
+2. **添加渲染函数**:
+```typescript
+const renderNewTypeContent = (data: any, props: FviewerProps) => {
+  return (
+    <div>
+      {/* 新类型的渲染逻辑 */}
+    </div>
+  );
+};
+```
+
+3. **在renderContent中添加case**:
+```typescript
+case 'newtype':
+  return renderNewTypeContent(data, props);
+```
+
+### 添加新的业务适配器
+
+1. **创建适配器组件**:
+```typescript
+// src/adopters/NewBusinessReader.tsx
+const NewBusinessReader: React.FC<NewBusinessReaderProps> = (props) => {
+  // 业务逻辑处理
+  return (
+    <Fviewer
+      data={processedData}
+      eventsEmit={handleEvents}
+      // ... 其他属性
+    />
+  );
+};
+```
+
+2. **遵循HOC模式**: 适配器应该包装核心组件，处理业务逻辑
+
+### 主题定制
+
+```typescript
+const customTheme: AppTheme = {
+  colors: {
+    primary: '#your-primary-color',
+    background: '#your-background-color',
+    text: '#your-text-color',
+    // ... 其他颜色
+  },
+  space: {
+    radius: 'md',
+    padding: 'md',
+    // ... 其他间距
+  }
+};
+```
+
+## API参考
+
+### 事件类型
+
+| 事件名 | 描述 | 数据格式 |
+|--------|------|----------|
+| `pageChange` | 页面变化 | `{ pageNumber: number, totalPages: number }` |
+| `markdown_scroll` | Markdown滚动 | `{ scrollTop: number, scrollHeight: number }` |
+| `zoomChange` | 缩放变化 | `{ scale: number }` |
+| `annotationChange` | 标注变化 | `{ annotation: Annotation }` |
+| `viewer:close` | 关闭查看器 | `undefined` |
+
+### 工具配置
+
+```typescript
+interface ToolsConfig {
+  annotation?: boolean;  // 标注功能
+  download?: boolean;    // 下载功能
+  zoom?: boolean;        // 缩放功能
+  close?: boolean;       // 关闭功能
+  navigation?: boolean;  // 导航功能
+}
+```
+
+## 技术栈
+
+- **React 18**: 核心框架
+- **TypeScript**: 类型安全
+- **styled-components v6**: CSS-in-JS样式
+- **PDF.js**: PDF渲染
+- **axios**: HTTP请求
+- **@mxmweb/rtext**: 富文本渲染
+
+## 开发环境
+
+```bash
+# 安装依赖
+npm install
+
+# 启动开发服务器
+npm run dev
+
+# 构建生产版本
+npm run build
+
+# 类型检查
+npm run type-check
+```
+
+## 注意事项
+
+1. **缓存策略**: Stream业务流使用5分钟缓存过期时间，可根据需要调整
+2. **无限滚动**: Markdown模式下的无限滚动需要后端支持块级数据返回
+3. **主题配置**: 建议使用统一的主题配置，确保UI一致性
+4. **错误处理**: 所有网络请求都有错误处理，建议在业务层添加重试机制
+
+## 更新日志
+
+### v1.0.0
+- 初始版本发布
+- 支持PDF、Markdown、图片、文本、HTML格式
+- 实现Stream业务流和静态文件两种适配器
+- 支持无限滚动和智能缓存
+- 完整的主题化支持

package/adopters/GientechStreamReader.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 import { AppTheme, Annotation, MDAnnotation, TableAnnotation, ToolsConfig } from '../core/types';
+import { Styles } from '@mxmweb/zui';
 export interface GientechStreamReaderProps {
     convertedFilePath: string;
     csrfToken?: string;
@@ -15,10 +16,7 @@ export interface GientechStreamReaderProps {
     authorization?: string;
     eventsEmit?: (name: string, data?: any, innerFn?: any) => void;
     tools?: Partial<ToolsConfig>;
-    styles?: {
-        theme?: AppTheme;
-        mode?: 'light' | 'dark';
-    };
+    styles?: Styles;
     customComponents?: {
         LoadingComponent?: React.ComponentType<{
             status: string;