📁 File Preview Kit

一个功能强大的文件预览库，支持多种文件格式的在线预览，包括图片、视频、PDF、Office 文档、代码文件等。

✨ 特性

• 🖼️ 图片预览：支持缩放、旋转、翻转等交互操作（基于 Viewer.js）
• 📄 PDF 预览：完整的 PDF 渲染，支持翻页、缩放（基于 PDF.js）
• 💻 代码高亮：支持多种编程语言的语法高亮（基于 Highlight.js）
• 📊 Office 文档：支持 Excel、Word 文档预览
• 📝 Markdown 渲染：将 Markdown 渲染为 HTML（基于 Marked.js）
• 🎬 多媒体支持：视频、音频播放
• 📦 压缩包预览：显示 ZIP 文件内容列表
• 🎨 现代化 UI：精美的界面设计和流畅的动画效果
• 🔧 TypeScript 支持：完整的类型定义
• 📦 轻量级打包：基于 Vite 构建，支持 ES6/ES2020
• ⚛️ 框架友好：可在 React、Vue 等项目中直接使用

📦 安装

npm install file-preview-kit
# or
yarn add file-preview-kit
# or
pnpm add file-preview-kit

🚀 快速开始

在 React 项目中使用

import { useState } from 'react';
import { handlePreview } from 'file-preview-kit';
import 'file-preview-kit/style.css';

function FileUpload() {
  const handleFileChange = async (event) => {
    const file = event.target.files[0];
    if (file) {
      try {
        const instance = await handlePreview(file);
        // instance.close(); // 手动关闭
      } catch (error) {
        console.error('预览失败:', error);
      }
    }
  };

  return <input type="file" onChange={handleFileChange} />;
}

详细的 React 使用说明请查看 REACT_USAGE.md

基本使用（原生 JavaScript）

import { handlePreview } from 'file-preview-kit';
import 'file-preview-kit/style.css';

// 在文件输入框的 change 事件中使用
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (file) {
    const instance = await handlePreview(file);

    // 可以手动关闭预览
    // instance.close();

    // 可以销毁实例
    // instance.destroy();
  }
});

带选项的使用

import { handlePreview } from 'file-preview-kit';

await handlePreview(file, {
  showFileName: true,          // 显示文件名（默认 true）
  showCloseButton: true,       // 显示关闭按钮（默认 true）
  pdfScale: 1.5,              // PDF 初始缩放比例（默认 1.5）
  onClose: () => {            // 关闭回调
    console.log('预览已关闭');
  },
  onError: (error) => {       // 错误回调
    console.error('预览出错：', error);
  },
  onLoad: () => {             // 加载完成回调
    console.log('预览加载完成');
  }
});

创建可重用的预览器实例

import { createPreview } from 'file-preview-kit';

// 创建预览器实例
const previewer = createPreview({
  showFileName: true,
  pdfScale: 2.0
});

// 预览不同的文件
await previewer.preview(file1);
await previewer.preview(file2);

// 销毁预览器
previewer.destroy();

使用类

import { FilePreview } from 'file-preview-kit';

const preview = new FilePreview({
  showFileName: true,
  onClose: () => console.log('关闭')
});

const instance = await preview.preview(file);

// 关闭预览
instance.close();

// 销毁实例
instance.destroy();

📋 支持的文件类型

| 类型 | 扩展名 | 功能 | |------|--------|------| | 图片 | jpg, png, gif, webp, svg 等 | 缩放、旋转、翻转 | | 视频 | mp4, webm, ogg 等 | 播放控制 | | 音频 | mp3, wav, ogg 等 | 播放控制 | | PDF | pdf | 翻页、缩放 | | JSON | json | 格式化 + 语法高亮 | | 代码 | js, ts, py, java, cpp, go 等 | 语法高亮 | | Markdown | md, markdown | 渲染为 HTML | | HTML | html, htm | iframe 预览 | | Excel | xlsx, xls | 表格展示 | | Word | docx, doc | 文档预览 | | 压缩包 | zip, tar | 文件列表 | | 文本 | txt, csv 等 | 纯文本展示 |

🎨 API

handlePreview(file, options?)

便捷函数，用于快速预览文件。

参数：

• file: File - 要预览的文件对象
• options?: PreviewOptions - 预览选项（可选）

返回：

• Promise<PreviewInstance> - 预览实例

createPreview(options?)

创建一个可重用的预览器实例。

参数：

• options?: PreviewOptions - 预览选项（可选）

返回：

• FilePreview - 预览器实例

PreviewOptions

interface PreviewOptions {
  /** 容器元素或选择器，如果不提供则创建全屏模态框 */
  container?: HTMLElement | string;

  /** 是否显示文件名 */
  showFileName?: boolean;

  /** 是否显示关闭按钮 */
  showCloseButton?: boolean;

  /** 自定义主题色 */
  themeColor?: string;

  /** PDF 初始缩放比例 */
  pdfScale?: number;

  /** 图片查看器配置 */
  imageViewerOptions?: any;

  /** 关闭回调 */
  onClose?: () => void;

  /** 错误回调 */
  onError?: (error: Error) => void;

  /** 加载完成回调 */
  onLoad?: () => void;
}

PreviewInstance

interface PreviewInstance {
  /** 关闭预览 */
  close: () => void;

  /** 销毁实例 */
  destroy: () => void;
}

🛠️ 开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 预览构建结果
npm run preview

📦 依赖库

本项目基于以下优秀的开源库：

• PDF.js - PDF 渲染
• Viewer.js - 图片查看器
• Highlight.js - 代码语法高亮
• Marked.js - Markdown 解析
• SheetJS - Excel 文件处理
• Mammoth.js - Word 文档转换
• JSZip - ZIP 文件处理

📄 License

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📮 联系

如有问题或建议，请提交 Issue。