# 🚀 画廊组件快速使用指南

## 📦 5分钟快速集成

### 1️⃣ **导入组件**

```typescript
import { StageGalleryModalComponent, GalleryConfig } from '@/modules/project/components/stage-gallery-modal';

@Component({
  imports: [StageGalleryModalComponent]
})
export class YourComponent {
  showGallery = false;
  galleryConfig: GalleryConfig | null = null;
}
```

### 2️⃣ **准备数据**

```typescript
openGallery() {
  this.galleryConfig = {
    spaceId: '空间ID',
    spaceName: '客厅',
    stageId: '阶段ID',
    stageName: '渲染',
    files: [
      {
        id: '文件ID',
        name: '文件名.jpg',
        url: '文件URL',
        size: 1024000,  // 可选
        uploadTime: new Date()  // 可选
      }
    ],
    canEdit: true  // 是否显示删除和上传按钮
  };
  
  this.showGallery = true;
}
```

### 3️⃣ **添加到模板**

```html
<app-stage-gallery-modal
  [visible]="showGallery"
  [config]="galleryConfig"
  (close)="showGallery = false; galleryConfig = null"
  (deleteFile)="onDelete($event)"
  (uploadFiles)="onUpload($event)"
  (previewFile)="onPreview($event)">
</app-stage-gallery-modal>
```

### 4️⃣ **处理事件（可选）**

```typescript
onDelete(event: { file: any; event: Event }) {
  console.log('删除:', event.file.name);
  // 你的删除逻辑
}

onUpload(event: Event) {
  const input = event.target as HTMLInputElement;
  console.log('上传:', input.files);
  // 你的上传逻辑
}

onPreview(file: any) {
  console.log('预览:', file.name);
  // 你的预览逻辑（非图片文件）
}
```

---

## ✨ 就这么简单！

画廊会自动处理：
- ✅ 图片和文档的预览
- ✅ 大图全屏查看
- ✅ 左右切换图片
- ✅ 响应式布局
- ✅ 精美动画

---

## 🎨 视觉效果

### 桌面端
```
┌──────────────────────────────────────────┐
│ [🏠] 渲染 - 客厅               [×]       │  ← 渐变紫色头部
│      📁 6 个文件                          │
├──────────────────────────────────────────┤
│  [图1] [图2] [图3] [图4]                │  ← 自适应网格
│  [图5] [图6] [PDF] [图7]                │  ← 阴影 + hover
├──────────────────────────────────────────┤
│           [📤 上传文件]                  │  ← 渐变按钮
└──────────────────────────────────────────┘
```

### 手机端
```
┌────────────────────┐
│ [🏠] 渲染   [×]    │
│     📁 6 个文件     │
├────────────────────┤
│   [图1]   [图2]   │  ← 2列布局
│   [图3]   [图4]   │
│   [图5]   [图6]   │
├────────────────────┤
│   [📤 上传文件]   │  ← 全宽按钮
└────────────────────┘
```

---

## 🎯 核心特性

### **功能**
- 🖼️ 图片大图预览（点击查看）
- ⬅️➡️ 左右切换图片
- 🗑️ 删除文件（带确认）
- 📤 上传文件
- 📁 文档预览（PDF、DWG等）

### **设计**
- 🌈 渐变紫色主题
- ✨ 玻璃拟态效果
- 🎬 流畅动画
- 📱 完全响应式

### **体验**
- 👆 大按钮易操作
- 📊 信息清晰完整
- 🚀 性能优化
- 🎯 视觉反馈

---

## 📱 自适应说明

| 屏幕尺寸 | 列数 | 间距 | 特殊处理 |
|----------|------|------|----------|
| **桌面** (>1024px) | 自适应 | 24px | hover显示删除 |
| **平板** (768-1024px) | 3列 | 20px | 始终显示删除 |
| **手机** (<768px) | 2列 | 12px | 全宽按钮 |

---

## 💡 使用建议

### ✅ **推荐做法**
```typescript
// 1. 使用 ChangeDetectionStrategy.OnPush
@Component({
  changeDetection: ChangeDetectionStrategy.OnPush
})

// 2. 调用 markForCheck 更新视图
this.galleryConfig = newConfig;
this.cdr.markForCheck();

// 3. 关闭时清理状态
closeGallery() {
  this.showGallery = false;
  this.galleryConfig = null;
}
```

### ❌ **避免做法**
```typescript
// 1. 不要在 config 中使用复杂对象
// ❌ 错误
files: this.allFiles  // 引用

// ✅ 正确
files: [...this.allFiles]  // 拷贝

// 2. 不要忘记处理关闭事件
// ❌ 错误
<app-stage-gallery-modal [visible]="true" />

// ✅ 正确
<app-stage-gallery-modal 
  [visible]="showGallery"
  (close)="showGallery = false" />
```

---

## 🔗 更多文档

- 📄 **完整文档**: `NEW_GALLERY_COMPONENT.md`
- 🎨 **设计规范**: 查看 SCSS 中的注释
- 🐛 **问题反馈**: 联系开发团队

---

## 🎉 开始使用吧！

只需4步，即可拥有精美的图片画廊！

```typescript
// 1. 导入
import { StageGalleryModalComponent, GalleryConfig } from '@/components/stage-gallery-modal';

// 2. 配置
galleryConfig: GalleryConfig = { /* ... */ };

// 3. 使用
<app-stage-gallery-modal [visible]="true" [config]="galleryConfig" />

// 4. 完成！
```

---

**快速上手时间**: ~5分钟  
**集成难度**: ⭐⭐☆☆☆ (简单)  
**视觉效果**: ⭐⭐⭐⭐⭐ (精美)