npm package: @ibiz-template-plugin/ibiz-file-previewer
Description: iBiz文件预览器
Author: iBizLab
Latest version: 0.0.22

# 文件预览

## 项目初始化

1. 使用 Vite 创建 preact + TypeScript 项目
2. 安装必要依赖：sass（SCSS 支持）、tsc（TypeScript 类型检查）
3. 配置项目结构，创建组件目录和样式目录

## 预览壳组件

1. 创建 `file-preview-shell.tsx` 组件
2. 创建 `file-preview-controller.ts` 控制器模块
3. 实现参数处理逻辑：
   - 接收 name、id、url 参数
   - 处理 id 和 url 的二选一逻辑
   - 处理 name 参数的获取逻辑
   - 实现 url 转 id 的下载和上传逻辑
4. 实现文件信息展示：
   - 解析文件名
   - 解析引擎信息
5. 实现下载功能模块：
   - 下载源文件
   - 复制文本内容
   - 导出为 PDF（非 PDF 文件）
   - 导出为 MD（非 MD 文件）
6. 实现文件类型处理：
   - 基于文件后缀解析文件类型
   - 基于文件类型计算文件引擎
   - 动态分发至对应预览组件
7. 逻辑与 UI 分离：
   - 预览壳组件负责界面绘制
   - 控制器模块实现功能逻辑

### 参数输入

| 参数名称              | 类型                                                         | 说明                                                         | 默认值 |
| --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------ |
| theme                 | `'light' \| 'dark'`                                           | 主题                                                         | 'dark' |
| selector              | string                                                       | 预览组件的挂载点（必填）                                     | ---    |
| getContent            | `(id: string,type: string,cat: string): Promise<string \| object \| undefined>` | 获取预览文件的内容，参数依次为：文件标识，文件类型，存储位置名称 | ---    |
| getImgContent         | `(id: string, type: FileType, cat: string): Promise<string>` | 获取预览图片内容，参数依次为：文件标识，文件类型，存储目录，标准图片返回值必须为：图片url路径或者图片Base64内容，SVG图片必须为：图片html内容 | ---    |
| upLoadFileToOss       | `(url: string): Promise<{ id: string; name: string; cat: string } \| undefined>` | 上传文件至oss，参数为上传路径                                | ---    |
| downLoadFile          | `(id: string, name: string, cat: string): Promise<void>`     | 下载文件，参数依次为：文件标识，文件名称，存储位置名称       | ---    |
| actionSuccessCallBack | `(type: string): Promise<void>`                              | 文件操作成功回调，参数为文件类型                             | ---    |

## 预览组件

1. 实现组件输入参数处理：

   - 接收预览组件控制器对象

2. 实现交互控制：

   - 根据不同的文件引擎类型实现以下功能：

     MD引擎类型：预览、查看大纲、下载源文件、复制文本内容

     HTML引擎类型：预览、下载源文件、复制文本内容

     TXT引擎类型：预览、下载源文件、复制文本内容

     PDF引擎类型：预览、缩略图、顺/逆时针旋转、上/下一页、引擎模式切换、显示模式切换、缩小/放大、重置、下载源文件

     IMG引擎类型：预览、顺/逆时针旋转、图片拖拽、显示模式切换、缩小/放大、重置、下载源文件、复制文本内容

3. 逻辑与 UI 分离：

   - 预览组件负责界面绘制
   - 控制器模块实现功能逻辑

## 样式实现

1. 使用 SCSS 实现主题和响应式样式，支持暗色和亮色两套主题
2. 确保 HTML 结构语义化和可访问性

## 技术实现规范

- 使用 TypeScript 实现类型安全的组件开发
- 使用 SCSS 实现响应式样式及组件主题
- 确保 HTML 结构语义化且符合可访问性标准

## 文件引擎

### MD引擎

| 文件扩展名 | 支持情况 |
| ---------- | -------- |
| html       | 已支持   |
| md         | 已支持   |

### HTML引擎

| 文件扩展名 | 支持情况 |
| ---------- | -------- |
| xls        | 已支持   |
| xlsx       | 已支持   |
| et         | 已支持   |
| doc        | 已支持   |
| docx       | 已支持   |
| wps        | 已支持   |

### TXT引擎

| 文件扩展名 | 支持情况 |
| ---------- | -------- |
| txt        | 已支持   |
| xml        | 已支持   |
| json       | 已支持   |

### PDF引擎

| 文件扩展名 | 支持情况 |
| ---------- | -------- |
| pdf        | 已支持   |
| doc        | 已支持   |
| docx       | 已支持   |
| wps        | 已支持   |
| ppt        | 已支持   |
| pptx       | 已支持   |

### IMG引擎

| 文件扩展名 | 支持情况 |
| ---------- | -------- |
| jpg        | 已支持   |
| png        | 已支持   |
| gif        | 已支持   |
| bmp        | 已支持   |
| jpeg       | 已支持   |
| webp       | 已支持   |
| ico        | 已支持   |
| svg        | 已支持   |

**注意**：同一个文件扩展名可能有多个引擎，如：**doc**，**docx**，**wps** 等，这些文件均可通过切换引擎的方式更改预览内容