**现代化 UI** - 简洁现代的界面设计，流畅动画
- 
**多格式支持** - 支持 20+ 种文件格式
- 
**两种展示模式** - 全屏弹窗 **或** 嵌入式内联预览
- 
**强大的图片查看器** - 缩放、旋转、拖拽、滚轮缩放
- 
**自定义视频播放器** - 基于 Video.js,支持多种视频格式
- 
**自定义音频播放器** - 精美的音频控制界面
- 
**PDF 查看器** - 支持分页浏览
- 
**Office 文档支持** - Word、Excel、PowerPoint 文件预览
- 
**Markdown 渲染** - 支持 GitHub Flavored Markdown
- 
**代码高亮** - 支持 40+ 种编程语言
- 
**响应式设计** - 适配各种屏幕尺寸
- 
**键盘导航** - 支持方向键、Home、End 和 ESC 键
## 📦 安装
```bash
# 使用 npm
npm install @eternalheart/vue-file-preview
# 使用 yarn
yarn add @eternalheart/vue-file-preview
# 使用 pnpm
pnpm add @eternalheart/vue-file-preview
```
**重要提示：** 你还需要导入 CSS 文件：
```ts
import '@eternalheart/vue-file-preview/style.css';
```
> **说明：** PDF 预览所需的 `pdfjs-dist` 依赖会自动安装，无需额外操作。
### PDF.js 配置（可选）
如果你需要预览 PDF 文件，建议配置 PDF.js 使用本地静态文件以提高性能和稳定性：
#### 方式 1: 使用 CDN（默认）
默认情况下，组件会自动使用 unpkg CDN 加载 PDF.js，无需额外配置。
#### 方式 2: 使用本地静态文件（推荐用于生产环境）
1. 将 PDF.js 文件复制到你的 public 目录：
```bash
cp -r node_modules/pdfjs-dist/legacy/build/pdf.worker.min.mjs public/pdfjs/
cp -r node_modules/pdfjs-dist/cmaps public/pdfjs/
cp -r node_modules/pdfjs-dist/standard_fonts public/pdfjs/
cp -r node_modules/pdfjs-dist/wasm public/pdfjs/
```
2. 在应用入口配置 PDF.js：
```ts
import * as pdfjsLib from 'pdfjs-dist/legacy/build/pdf.mjs';
import { configurePdfWorker } from '@eternalheart/vue-file-preview';
configurePdfWorker(pdfjsLib, {
workerSrc: '/pdfjs/pdf.worker.min.mjs',
cMapUrl: '/pdfjs/cmaps/',
cMapPacked: true,
standardFontDataUrl: '/pdfjs/standard_fonts/',
wasmUrl: '/pdfjs/wasm/',
});
```
请在客户端应用初始化阶段、首次渲染 PDF 前调用。Worker 必须使用与当前 `pdfjs-dist` 版本匹配的 legacy 构建。
#### 使用 Vite 自动复制（推荐）
在 `vite.config.ts` 中配置自动复制：
```ts
import { defineConfig } from 'vite';
import { viteStaticCopy } from 'vite-plugin-static-copy';
export default defineConfig({
plugins: [
viteStaticCopy({
targets: [
{
src: 'node_modules/pdfjs-dist/legacy/build/pdf.worker.min.mjs',
dest: 'pdfjs'
},
{
src: 'node_modules/pdfjs-dist/cmaps',
dest: 'pdfjs'
},
{
src: 'node_modules/pdfjs-dist/standard_fonts',
dest: 'pdfjs'
},
{
src: 'node_modules/pdfjs-dist/wasm',
dest: 'pdfjs'
}
]
})
]
});
```
### Vite 打包提示（AVIF 解码器）
如果你的项目使用 Vite 打包,且项目里安装了 `@jsquash/avif`(直接安装或被其它依赖间接引入),生产构建时可能报错:
```
[commonjs--resolver] Invalid value "iife" for option "worker.format"
- UMD and IIFE output formats are not supported for code-splitting builds.
file: .../@jsquash/avif/codec/enc/avif_enc_mt.js
```
原因:`@jsquash/avif` 内部包含一个使用代码分割的多线程 worker,而 Vite 默认的 `worker.format` 是 `'iife'`,不支持多 chunk 拆分。
**解决方法** —— 在你的 `vite.config.ts` 中加入:
```ts
export default defineConfig({
// ... 原有配置
worker: {
format: 'es',
},
});
```
`'es'` 会产生 module worker(`type: 'module'`),现代浏览器全部支持,且兼容代码分割。
> 说明:`@jsquash/avif` 仅在浏览器不原生支持 AVIF 时作为兜底使用(Chrome 85+、Firefox 93+、Safari 16+ 均已原生支持)。如果你的目标浏览器都覆盖原生支持范围,也可以直接从依赖中移除 `@jsquash/avif`。
## 🚀 快速开始
### 基础用法
```vue