yss-project/docs/GALLERY_QUICK_START.md

🚀 画廊组件快速使用指南

📦 5分钟快速集成

1️⃣ 导入组件

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

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

2️⃣ 准备数据

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️⃣ 添加到模板

<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️⃣ 处理事件（可选）

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	全宽按钮

---

💡 使用建议

✅ 推荐做法

// 1. 使用 ChangeDetectionStrategy.OnPush
@Component({
  changeDetection: ChangeDetectionStrategy.OnPush
})

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

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

❌ 避免做法

// 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步，即可拥有精美的图片画廊！

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

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

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

// 4. 完成！

---

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