@mxmweb/fviewer 1.1.16 → 1.2.0

package/README.md

@@ -1 +1,591 @@
-# 工具库架构初始化
+# @mxmweb/fviewer
+
+一个功能强大的文件查看器库，支持多种文件格式的解析和显示，包括PDF、图片、文本、Markdown等格式。
+
+## 安装与依赖
+
+本库为“易安装应用库”，仅外置最小运行时依赖。请在宿主项目中安装以下对等依赖（peerDependencies）：
+
+```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
+```
+
+PDF.js 的 worker 需由宿主自行注册一次（任意应用初始化位置）：
+
+```ts
+import * as pdfjsLib from 'pdfjs-dist';
+
+// 方式一：指向你静态资源中的 worker 文件
+pdfjsLib.GlobalWorkerOptions.workerSrc = '/worker/pdf.worker.min.js';
+
+// 方式二：直接引入（需确保构建可访问该路径）
+// import 'pdfjs-dist/build/pdf.worker.min.js';
+```
+
+> 说明：为降低包体积，`@mxmweb/rtext` 与 `pdfjs-dist` 均已外置；`react/react-dom/@mxmweb/zui/styled-components` 作为运行时依赖亦需由宿主提供。
+
+## 核心组件
+
+### StaticFileReader
+
+静态文件阅读器组件，用于加载和显示本地或远程静态文件。
+
+#### 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` - 内容类名（可选）
+
+#### 调用实例
+
+```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
+      }}
+    />
+  );
+}
+```
+
+#### 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';
+
+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;
+    }
+  };
+
+  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'
+          }
+        }
+      }}
+    />
+  );
+}
+```
+
+#### 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'
+});
+```
+
+### parsePdfFile
+
+专门用于解析PDF文件的函数。
+
+```tsx
+import { parsePdfFile } from '@mxmweb/fviewer';
+
+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文件解析函数。
+
+```tsx
+import { parseMarkdownFile } from '@mxmweb/fviewer';
+
+const mdResult = await parseMarkdownFile(markdownContent, {
+  fileName: 'readme.md'
+});
+```
+
+### detectFileType
+
+文件类型检测函数。
+
+```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;
+  // 事件回调
+  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;
+}
+```
+
+### GientechStreamReaderProps
+
+流式文件阅读器组件的属性接口。
+
+```tsx
+interface GientechStreamReaderProps {
+  // 文件相关
+  convertedFilePath: string;
+  csrfToken?: string;
+  fileName?: string;
+  fileType: string;
+  initialPage?: number;
+  totalPages?: number;
+  annotations?: (Annotation | MDAnnotation | TableAnnotation)[];
+  // 用户信息
+  userName?: string;
+  userId?: string;
+  pageSize?: number;
+  // API配置
+  streamApiUrl?: string;
+  authorization?: string;
+  // 事件回调
+  eventsEmit?: (name: string, data?: any, innerFn?: any) => void;
+  // 工具配置
+  tools?: Partial<ToolsConfig>;
+  // 样式配置
+  styles?: Styles;
+  // 自定义组件
+  customComponents?: {
+    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标注数据接口。
+
+```tsx
+interface MDAnnotation {
+  id: string;
+  start: number;
+  end: number;
+  content?: string;
+  color?: string;
+}
+```
+
+### TableAnnotation
+
+表格标注数据接口。
+
+```tsx
+interface TableAnnotation {
+  id: string;
+  offsets: [number, number][];
+  content?: string;
+  color?: string;
+}
+```
+
+### 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;
+}
+```
+
+### Styles
+
+样式配置接口，来自 @mxmweb/zui 包。
+
+```tsx
+import { Styles } from '@mxmweb/zui';
+
+// Styles 是一个通用的样式配置接口
+// 用于配置组件的主题和样式
+```
+
+### ParseResult
+
+文件解析结果接口。
+
+```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';
+```

package/adopters/GientechStreamReader.d.ts

@@ -1,11 +1,13 @@
 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;
     fileName?: string;
     fileType: string;
     initialPage?: number;
+    initialZoom?: number;
     totalPages?: number;
     annotations?: (Annotation | MDAnnotation | TableAnnotation)[];
     userName?: string;
@@ -15,10 +17,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;

package/adopters/StaticFileReader.d.ts

@@ -1,7 +1,7 @@
 import { default as React } from 'react';
 import { AppTheme, Annotation, MDAnnotation, TableAnnotation, ToolsConfig } from '../core/types';
 export interface StaticFileReaderProps {
-    fileUrl: string;
+    fileUrl?: string;
     fileType?: string;
     fileName?: string;
     token?: string;

package/core/Fviewer.d.ts

@@ -23,6 +23,7 @@ export interface FviewerProps {
     totalPage?: number;
     currentPage?: number;
     scale?: number;
+    initialZoom?: number;
     rotation?: number;
     eventsEmit?: (name: string, data?: any, innerFn?: any) => void;
     styles?: {

package/core/index.d.ts

@@ -1,6 +1,6 @@
 import { default as Fviewer, FviewerProps } from './Fviewer';
 import { default as PdfRender, PdfRenderProps } from './PdfRender';
-import { AppTheme, Annotation, ToolsConfig } from './types';
+import { Annotation, ToolsConfig } from './types';
 export { Fviewer, PdfRender };
-export type { FviewerProps, PdfRenderProps, AppTheme, Annotation, ToolsConfig };
+export type { FviewerProps, PdfRenderProps, Annotation, ToolsConfig };
 export default Fviewer;

package/core/types.d.ts

@@ -1,31 +1,4 @@
-export 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;
-}
+export type { Styles as AppTheme } from '@mxmweb/zui';
 export interface Annotation {
     id: string;
     pageNumber: number;

package/examples/CoreReader/index.d.ts

@@ -0,0 +1 @@
+export default function CoreReaderDemo(): import("react/jsx-runtime").JSX.Element;

package/examples/StaticFileReader/index.d.ts

@@ -0,0 +1 @@
+export default function StaticFileReaderDemo(): import("react/jsx-runtime").JSX.Element;