vue-document-components/README.md

A collection of Vue.js components for document preview, file management, and media handling

# Vue Document Components

🚀 一个功能丰富的 Vue.js 文档处理组件库，包含 PDF 预览、图片预览和文件上传等实用组件。

## ✨ 特性

- 📱 **响应式设计** - 完美适配桌面端和移动端
- 🖼️ **多组件支持** - PDF预览、图片预览、文件上传等
- ⬇️ **丰富功能** - 下载、预览、缩放、旋转等操作
- 🔧 **高度可定制** - 丰富的配置选项和事件
- 🎨 **现代化UI** - 毛玻璃效果、渐变色彩、流畅动画
- 💫 **精美动效** - 悬浮效果、光影动画、过渡动画
- 📝 **TypeScript支持** - 完整的类型定义
- 🌍 **国际化** - 支持自定义文本内容
- ⚡ **轻量级** - 按需引入，体积小巧
- 🎭 **主题系统** - 内置现代化主题样式

## 📦 安装

```bash
npm install vue-document-components element-plus @element-plus/icons-vue
```

或使用 yarn:

```bash
yarn add vue-document-components element-plus @element-plus/icons-vue
```

## 🚀 快速开始

### Vue 3 全量引入 (推荐)

```javascript
import { createApp } from 'vue';
import ElementPlus from 'element-plus';
import 'element-plus/dist/index.css';
import * as ElementPlusIconsVue from '@element-plus/icons-vue';
import VueDocumentComponents from 'vue-document-components';

const app = createApp(App);

// 注册 Element Plus
app.use(ElementPlus);

// 注册 Element Plus 图标
for (const [key, component] of Object.entries(ElementPlusIconsVue)) {
  app.component(key, component);
}

// 注册所有组件
app.use(VueDocumentComponents);

app.mount('#app');
```

### Vue 3 按需引入

```javascript
import { createApp } from 'vue';
import { PdfPreviewDialog, ImagePreviewDialog, FileUploader } from 'vue-document-components';

const app = createApp(App);

// 只注册需要的组件
app.component('PdfPreviewDialog', PdfPreviewDialog);
app.component('ImagePreviewDialog', ImagePreviewDialog);
app.component('FileUploader', FileUploader);

app.mount('#app');
```

### Composition API 使用

```vue
<template>
  <div>
    <el-button @click="showPdf">预览PDF</el-button>
    
    <pdf-preview-dialog
      ref="pdfDialogRef"
      :pdf-url="pdfUrl"
      title="用户手册"
      @preview-loaded="onPreviewLoaded"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';

const pdfUrl = ref('/path/to/document.pdf');
const pdfDialogRef = ref(null);

const showPdf = () => {
  pdfDialogRef.value?.open();
};

const onPreviewLoaded = () => {
  console.log('PDF预览加载成功');
};
</script>
```

### 单独引入组件 (Vue 3)

```vue
<script setup>
import { PdfPreviewDialog } from 'vue-document-components/lib/components';
</script>
```

## 📋 组件列表

### 1. PDF预览对话框 (PdfPreviewDialog)

功能丰富的PDF文档预览组件，支持全屏预览和下载。

```vue
<template>
  <div>
    <el-button @click="showPdf">预览PDF</el-button>
    
    <pdf-preview-dialog
      ref="pdfDialog"
      :pdf-url="pdfUrl"
      title="用户手册"
      filename="user-manual.pdf"
      @preview-loaded="onPreviewLoaded"
      @download-success="onDownloadSuccess"
    />
  </div>
</template>

<script>
export default {
  data() {
    return {
      pdfUrl: '/path/to/your/document.pdf'
    };
  },
  methods: {
    showPdf() {
      this.$refs.pdfDialog.open();
    },
    onPreviewLoaded() {
      console.log('PDF预览加载成功');
    },
    onDownloadSuccess() {
      console.log('PDF下载成功');
    }
  }
};
</script>
```

#### Props

| 属性名 | 类型 | 默认值 | 描述 |
|--------|------|--------|------|
| `pdfUrl` | `String` | *必填* | PDF文件的URL地址 |
| `title` | `String` | `'PDF预览'` | 对话框标题 |
| `allowDownload` | `Boolean` | `true` | 是否显示下载按钮 |
| `filename` | `String` | `'document.pdf'` | 下载时的文件名 |
| `downloadText` | `String` | `'下载文件'` | 下载按钮文本 |
| `closeText` | `String` | `'关闭'` | 关闭按钮文本 |

#### Events

| 事件名 | 描述 | 参数 |
|--------|------|------|
| `open` | 对话框打开时触发 | - |
| `close` | 对话框关闭时触发 | - |
| `preview-loaded` | PDF预览加载成功时触发 | - |
| `preview-error` | PDF预览加载失败时触发 | `error: Error` |
| `download-success` | 下载成功时触发 | - |

### 2. 图片预览对话框 (ImagePreviewDialog)

强大的图片预览组件，支持缩放、旋转等操作。

```vue
<template>
  <div>
    <el-button @click="showImage">预览图片</el-button>
    
    <image-preview-dialog
      ref="imageDialog"
      :image-url="imageUrl"
      title="产品图片"
      filename="product.jpg"
      @image-loaded="onImageLoaded"
    />
  </div>
</template>

<script>
export default {
  data() {
    return {
      imageUrl: '/path/to/your/image.jpg'
    };
  },
  methods: {
    showImage() {
      this.$refs.imageDialog.open();
    },
    onImageLoaded() {
      console.log('图片加载成功');
    }
  }
};
</script>
```

#### Props

| 属性名 | 类型 | 默认值 | 描述 |
|--------|------|--------|------|
| `imageUrl` | `String` | *必填* | 图片文件的URL地址 |
| `title` | `String` | `'图片预览'` | 对话框标题 |
| `allowDownload` | `Boolean` | `true` | 是否显示下载按钮 |
| `filename` | `String` | `'image.jpg'` | 下载时的文件名 |

#### Events

| 事件名 | 描述 | 参数 |
|--------|------|------|
| `open` | 对话框打开时触发 | - |
| `close` | 对话框关闭时触发 | - |
| `image-loaded` | 图片加载成功时触发 | - |
| `image-error` | 图片加载失败时触发 | `error: Error` |

### 3. 文件上传器 (FileUploader)

功能完整的文件上传组件，支持拖拽上传、文件预览等。

```vue
<template>
  <file-uploader
    upload-action="/api/upload"
    :multiple="true"
    :max-size="10"
    :limit="5"
    accept=".pdf,.jpg,.png,.doc"
    @success="onUploadSuccess"
    @error="onUploadError"
  />
</template>

<script>
export default {
  methods: {
    onUploadSuccess(response, file, fileList) {
      console.log('上传成功', response);
    },
    onUploadError(error, file, fileList) {
      console.error('上传失败', error);
    }
  }
};
</script>
```

#### Props

| 属性名 | 类型 | 默认值 | 描述 |
|--------|------|--------|------|
| `uploadAction` | `String` | *必填* | 上传地址 |
| `drag` | `Boolean` | `true` | 是否支持拖拽上传 |
| `multiple` | `Boolean` | `true` | 是否支持多选 |
| `accept` | `String` | `'*'` | 接受的文件类型 |
| `maxSize` | `Number` | `10` | 文件大小限制（MB） |
| `limit` | `Number` | `5` | 文件数量限制 |

#### Events

| 事件名 | 描述 | 参数 |
|--------|------|------|
| `success` | 上传成功时触发 | `response, file, fileList` |
| `error` | 上传失败时触发 | `error, file, fileList` |
| `progress` | 上传进度变化时触发 | `event, file, fileList` |

## 🎨 现代化样式特性

### ✨ 视觉效果
- **毛玻璃效果** - 使用 backdrop-filter 实现半透明模糊背景
- **渐变色彩** - 丰富的渐变色主题，提升视觉层次
- **阴影系统** - 多层次阴影效果，增强空间感
- **圆角设计** - 统一的圆角规范，更加柔和友好

### 🎭 动画效果
- **悬浮动画** - 按钮和卡片的微妙悬浮效果
- **光影扫过** - 按钮点击时的光影扫过动画
- **缩放过渡** - 平滑的缩放和位移过渡
- **加载动画** - 优雅的loading和进度动画

### 🎨 主题系统

组件库内置了完整的现代化主题系统：

```vue
<template>
  <!-- 自动应用现代化样式 -->
  <pdf-preview-dialog
    :pdf-url="pdfUrl"
    title="📖 产品说明书"
    download-text="💾 立即下载"
    :fallback-messages="{
      loadFailed: '📋 文档预览服务暂时不可用',
      downloadTip: '📥 请点击下载按钮获取完整文档'
    }"
  />
</template>

<script>
// 主题样式会自动导入
import { PdfPreviewDialog } from 'vue-document-components';
</script>
```

### 🎨 自定义CSS变量

你可以通过CSS变量来自定义主题：

```css
:root {
  /* 主色调 */
  --primary-color: #409eff;
  --secondary-color: #67c23a;
  
  /* 渐变色 */
  --primary-gradient: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  --success-gradient: linear-gradient(135deg, #409EFF, #67C23A);
  
  /* 圆角 */
  --radius-medium: 12px;
  --radius-large: 16px;
  
  /* 阴影 */
  --shadow-medium: 0 8px 24px rgba(0, 0, 0, 0.15);
  --shadow-color: 0 8px 32px rgba(64, 158, 255, 0.15);
}
```

### 组合使用

```vue
<template>
  <div class="document-manager">
    <!-- 文件上传 -->
    <file-uploader
      upload-action="/api/upload"
      @success="onUploadSuccess"
      @preview="onFilePreview"
    />
    
    <!-- PDF预览 -->
    <pdf-preview-dialog
      ref="pdfDialog"
      :pdf-url="currentPdfUrl"
    />
    
    <!-- 图片预览 -->
    <image-preview-dialog
      ref="imageDialog"
      :image-url="currentImageUrl"
    />
  </div>
</template>

<script>
export default {
  data() {
    return {
      currentPdfUrl: '',
      currentImageUrl: ''
    };
  },
  methods: {
    onUploadSuccess(response, file) {
      // 上传成功后可以预览
      this.onFilePreview(file);
    },
    
    onFilePreview(file) {
      const fileType = file.name.split('.').pop().toLowerCase();
      
      if (fileType === 'pdf') {
        this.currentPdfUrl = file.url;
        this.$refs.pdfDialog.open();
      } else if (['jpg', 'jpeg', 'png', 'gif'].includes(fileType)) {
        this.currentImageUrl = file.url;
        this.$refs.imageDialog.open();
      }
    }
  }
};
</script>
```

### TypeScript 支持

```typescript
import { 
  PdfPreviewDialogProps, 
  ImagePreviewDialogProps, 
  FileUploaderProps 
} from 'vue-document-components';

interface ComponentData {
  pdfConfig: Partial<PdfPreviewDialogProps>;
  imageConfig: Partial<ImagePreviewDialogProps>;
  uploaderConfig: Partial<FileUploaderProps>;
}

export default Vue.extend({
  data(): ComponentData {
    return {
      pdfConfig: {
        title: 'TypeScript示例',
        allowDownload: true
      },
      imageConfig: {
        title: '图片预览',
        filename: 'screenshot.png'
      },
      uploaderConfig: {
        maxSize: 20,
        accept: '.pdf,.jpg,.png'
      }
    };
  }
});
```

## 🎯 样式自定义

```scss
// 自定义PDF预览样式
::v-deep .pdf-preview-container .preview-toolbar {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

// 自定义图片预览样式
::v-deep .image-preview-container .image-controls {
  background: rgba(0, 0, 0, 0.8);
  border-radius: 8px;
}

// 自定义文件上传样式
::v-deep .file-uploader .upload-dragger {
  border: 2px dashed #409eff;
  border-radius: 8px;
}
```

## 📱 移动端适配

所有组件都内置了完整的移动端适配：

- 📱 响应式布局
- 👆 触摸友好的交互
- 📐 自适应字体和间距
- 🔄 横竖屏自动适配

## 🌍 浏览器兼容性

- ✅ Chrome 60+
- ✅ Firefox 55+
- ✅ Safari 12+
- ✅ Edge 79+
- ⚠️ IE 11 (需要polyfill支持)

## 🔧 依赖要求

### 必需依赖 (Peer Dependencies)

- **Vue 3.0+** - 使用最新的 Composition API
- **Element Plus 2.0+** - 现代化的 Vue 3 UI 组件库  
- **@element-plus/icons-vue 2.0+** - Element Plus 图标库

## 🐛 常见问题

### Q: 如何按需引入组件？

A: 可以通过多种方式按需引入：

```javascript
// 方式1: 通过配置选项
Vue.use(VueDocumentComponents, {
  components: ['PdfPreviewDialog', 'FileUploader']
});

// 方式2: 单独引入
import { PdfPreviewDialog } from 'vue-document-components';

// 方式3: 从组件目录引入
import PdfPreviewDialog from 'vue-document-components/lib/components/PdfPreviewDialog.vue';
```

### Q: 如何自定义上传接口？

A: FileUploader 组件支持完全自定义：

```vue
<file-uploader
  upload-action="/your/api/endpoint"
  :before-upload="customBeforeUpload"
  @success="handleUploadResponse"
/>
```

### Q: 支持哪些文件格式？

A: 
- PDF预览：支持所有标准PDF文件
- 图片预览：支持 jpg, jpeg, png, gif, webp 等
- 文件上传：支持任意格式（可通过 accept 属性限制）

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🤝 贡献

欢迎提交 Issues 和 Pull Requests！

## 📞 支持

如果这个组件库对你有帮助，请给个 ⭐️ Star！

有问题或建议？欢迎提交 [Issue](https://github.com/example/vue-document-components/issues)！