# Model Modal UI/UX 重构计划

> **Status**: Phase 1 Complete ✓  
> **Created**: 2026-02-06  
> **Target**: v2.x Release

---

## 1. 项目概述

### 1.1 背景与问题

当前 Model Modal 存在以下 UX 问题：

1. **空间利用率低** - 固定 800px 宽度，大屏环境下大量留白
2. **Tab 切换繁琐** - 4 个 Tab（Examples/Description/Versions/Recipes）隐藏了重要信息
3. **Examples 浏览不便** - 需持续向下滚动，无快速导航
4. **添加自定义示例困难** - 需滚动到底部，操作路径长

### 1.2 设计目标

- **空间效率**: 利用 header 以下、sidebar 右侧的全部可用空间
- **浏览体验**: 类似 Midjourney 的沉浸式图片浏览
- **信息架构**: 关键元数据固定可见，次要信息可折叠
- **操作效率**: 直觉化的键盘导航，减少点击次数

---

## 2. 设计方案

### 2.1 布局架构: Split-View Overlay

```
┌──────────────────────────────────────────────────────────────────────┐
│  HEADER (保持现有)                                                    │
├──────────┬───────────────────────────────────────────────────────────┤
│          │  ┌───────────────────────────┬────────────────────────┐   │
│ FOLDER   │  │                           │  MODEL HEADER          │   │
│ SIDEBAR  │  │      EXAMPLES SHOWCASE    │  ├─ Name               │   │
│ (可折叠)  │  │                           │  ├─ Creator + Actions  │   │
│          │  │   ┌─────────────────┐     │  ├─ Tags               │   │
│          │  │   │                 │     ├────────────────────────┤   │
│          │  │   │   MAIN IMAGE    │     │  COMPACT METADATA      │   │
│          │  │   │   (自适应高度)   │     │  ├─ Ver | Base | Size  │   │
│          │  │   │                 │     │  ├─ Location           │   │
│          │  │   └─────────────────┘     │  ├─ Usage Tips         │   │
│          │  │                           │  ├─ Trigger Words      │   │
│          │  │   [PARAMS PREVIEW]        │  ├─ Notes              │   │
│          │  │   (Prompt + Copy)         ├────────────────────────┤   │
│          │  │                           │  CONTENT TABS          │   │
│          │  │   ┌─────────────────┐     │  [Desc][Versions][Rec] │   │
│          │  │   │  THUMBNAIL RAIL │     │                        │   │
│          │  │   │  [1][2][3][4][+]│     │  TAB CONTENT AREA      │   │
│          │  │   └─────────────────┘     │  (Accordion / List)    │   │
│          │  └───────────────────────────┴────────────────────────┘   │
└──────────┴───────────────────────────────────────────────────────────┘
```

**尺寸规格**:
- Sidebar 展开: Left 60% | Right 40%
- Sidebar 折叠: Left 65% | Right 35%
- 最小宽度: 1200px (低于此值触发移动端适配)

### 2.2 左侧: Examples Showcase

#### 2.2.1 组件结构

| 组件 | 描述 | 优先级 |
|------|------|--------|
| Main Image | 自适应容器，保持原始比例，最大高度 70vh | P0 |
| Params Panel | 底部滑出面板，显示 Prompt/Negative/Params | P0 |
| Thumbnail Rail | 底部横向滚动条，支持点击跳转 | P0 |
| Add Button | Rail 最右侧 "+" 按钮，打开上传区 | P0 |
| Nav Arrows | 图片左右两侧悬停显示 | P1 |

#### 2.2.2 图片悬停操作

```
┌─────────────────┐
│ [👁] [📌] [🗑] │  ← 查看参数 | 设为预览 | 删除
│                 │
│     IMAGE       │
│                 │
└─────────────────┘
```

#### 2.2.3 键盘导航

| 按键 | 功能 | 说明 |
|------|------|------|
| ← | 上一个 Example | 循环（首张时到最后一张） |
| → | 下一个 Example | 循环（末张时到第一张） |
| I | Toggle Params Panel | 显示/隐藏图片参数 |
| C | Copy Prompt | 复制当前 Prompt 到剪贴板 |

### 2.3 右侧: Metadata + Content

#### 2.3.1 固定头部 (不可折叠)

```
┌────────────────────────┐
│ MODEL NAME        [×]  │
│ [👤 Creator] [🌐 Civ]  │
│ [tag1] [tag2] [tag3]   │
├────────────────────────┤
│ Ver: v1.0  Size: 96MB  │
│ Base: SDXL             │
│ 📁 /path/to/file       │
├────────────────────────┤
│ USAGE TIPS        [✏️] │
│ [strength: 0.8] [+]    │
├────────────────────────┤
│ TRIGGER WORDS     [✏️] │
│ [word1] [word2]  [📋]  │
├────────────────────────┤
│ NOTES             [✏️] │
│ "Add your notes..."    │
└────────────────────────┘
```

#### 2.3.2 Tabs 设计

保留横向 Tab 切换，但优化内容展示：

| Tab | 内容 | 交互方式 |
|-----|------|----------|
| Description | About this version + Model Description | Accordion 折叠 |
| Versions | 版本列表卡片 | 完整列表视图 |
| Recipes | Recipe 卡片网格 | 网格布局 |

**Accordion 行为**:
- 手风琴模式：同时只能展开一个 section
- 默认：About this version 展开，Description 折叠
- 动画：300ms ease-out

### 2.4 全局导航

#### 2.4.1 Model 切换

| 按键 | 功能 |
|------|------|
| ↑ | 上一个 Model |
| ↓ | 下一个 Model |

**切换动画**:
1. 当前 Modal 淡出 (150ms)
2. 加载新 Model 数据
3. 新 Modal 淡入 (150ms)
4. 保持当前 Tab 状态（不重置到默认）

#### 2.4.2 首次使用提示

Modal 首次打开时，顶部显示提示条：
```
┌─────────────────────────────────────────────────────────────┐
│  💡 Tip: ↑↓ 切换模型 | ←→ 浏览示例 | I 查看参数 | ESC 关闭   │
└─────────────────────────────────────────────────────────────┘
```
- 3 秒后自动淡出
- 提供 "不再显示" 选项

---

## 3. 技术实现

### 3.1 文件结构变更

```
static/
├── js/
│   └── components/
│       └── model-modal/           # 新目录
│           ├── index.js           # 主入口
│           ├── ModelModal.js      # Modal 容器
│           ├── ExampleShowcase.js # 左侧展示
│           ├── ThumbnailRail.js   # 缩略图导航
│           ├── MetadataPanel.js   # 右侧元数据
│           ├── ContentTabs.js     # Tabs 容器
│           └── accordions/        # Accordion 组件
│               ├── DescriptionAccordion.js
│               └── VersionsList.js
├── css/
│   └── components/
│       └── model-modal/           # 新目录
│           ├── modal-overlay.css
│           ├── showcase.css
│           ├── thumbnail-rail.css
│           ├── metadata.css
│           └── tabs.css
```

### 3.2 核心 CSS 架构

```css
/* modal-overlay.css */
.model-overlay {
  position: fixed;
  top: var(--header-height);
  left: var(--sidebar-width, 250px);
  right: 0;
  bottom: 0;
  z-index: var(--z-modal);
  
  display: grid;
  grid-template-columns: 1.2fr 0.8fr;
  gap: 0;
  
  background: var(--bg-color);
  animation: modalSlideIn 0.2s ease-out;
}

.model-overlay.sidebar-collapsed {
  left: var(--sidebar-collapsed-width, 60px);
  grid-template-columns: 1.3fr 0.7fr;
}

/* 移动端适配 */
@media (max-width: 768px) {
  .model-overlay {
    left: 0;
    grid-template-columns: 1fr;
    grid-template-rows: auto 1fr;
  }
}
```

### 3.3 响应式断点

| 断点 | 布局 | 说明 |
|------|------|------|
| > 1400px | Split 60/40 | 大屏优化 |
| 1200-1400px | Split 50/50 | 标准桌面 |
| 768-1200px | Split 50/50 | 小屏桌面/平板 |
| < 768px | Stack | 移动端：Examples 在上，Metadata 在下 |

---

## 4. 实施阶段

### Phase 1: 核心重构 (预计 2-3 周)

**目标**: MVP 可用，基础功能完整

**任务清单**:

- [ ] 创建新的文件结构和基础组件
- [ ] 实现 Split-View Overlay 布局
  - [ ] CSS Grid 布局系统
  - [ ] Sidebar 状态联动
  - [ ] 响应式断点处理
- [ ] 迁移左侧 Examples 区域
  - [ ] Main Image 自适应容器
  - [ ] Thumbnail Rail 组件
  - [ ] Params Panel 滑出动画
- [ ] 实现新的快捷键系统
  - [ ] ↑↓ 切换 Model
  - [ ] ←→ 切换 Example
  - [ ] I/C/ESC 功能键
- [ ] 移除旧 Modal 的 max-width 限制
- [ ] 基础动画过渡

**验收标准**:
- [ ] 新布局在各种屏幕尺寸下正常显示
- [ ] 键盘导航正常工作
- [ ] 无阻塞性 Bug

---

### Phase 2: 体验优化 (预计 1-2 周)

**目标**: 信息架构优化，交互细节完善

**任务清单**:

- [ ] Accordion 组件实现
  - [ ] Description Tab 的折叠面板
  - [ ] 手风琴交互逻辑
  - [ ] 动画优化
- [ ] 右侧 Metadata 区域固定化
  - [ ] 滚动行为优化
  - [ ] 编辑功能迁移
- [ ] Example 添加流程优化
  - [ ] Rail 上的 "+" 按钮
  - [ ] Inline Upload Area
  - [ ] 拖拽上传支持
- [ ] Model 切换动画优化
  - [ ] 淡入淡出效果
  - [ ] 加载状态指示
- [ ] 首次使用提示

**验收标准**:
- [ ] Accordion 交互流畅
- [ ] 添加 Example 操作路径 < 2 步
- [ ] Model 切换视觉反馈清晰

---

### Phase 3: 功能完整化 (预计 1-2 周)

**目标**: 所有现有功能迁移完成

**任务清单**:

- [ ] Versions Tab 完整实现
  - [ ] 版本列表卡片
  - [ ] 下载/忽略/删除操作
  - [ ] 更新状态 Badge
- [ ] Recipes Tab 完整实现
  - [ ] Recipe 卡片网格
  - [ ] 复制/应用操作
- [ ] Tab 状态保持
  - [ ] 切换 Model 时保持当前 Tab
  - [ ] Tab 内容滚动位置记忆
- [ ] 所有编辑功能迁移
  - [ ] Model Name 编辑
  - [ ] Base Model 编辑
  - [ ] File Name 编辑
  - [ ] Tags 编辑
  - [ ] Usage Tips 编辑
  - [ ] Notes 编辑

**验收标准**:
- [ ] 所有现有功能可用
- [ ] 单元测试覆盖率 > 80%

---

### Phase 4: 打磨与优化 (预计 1 周)

**目标**: 性能优化，边缘 case 处理

**任务清单**:

- [ ] 移动端适配完善
  - [ ] Stack 布局优化
  - [ ] 触摸手势支持（滑动切换）
- [ ] 性能优化
  - [ ] 图片懒加载优化
  - [ ] 虚拟滚动（大量 Examples 时）
  - [ ] 减少重渲染
- [ ] 无障碍支持
  - [ ] ARIA 标签
  - [ ] 键盘导航焦点管理
  - [ ] 屏幕阅读器测试
- [ ] 动画性能优化
  - [ ] will-change 优化
  - [ ] 减少 layout thrashing

**验收标准**:
- [ ] Lighthouse Performance > 90
- [ ] 无障碍检查无严重问题

---

### Phase 5: 发布准备 (预计 3-5 天)

**目标**: 稳定版本，文档完整

**任务清单**:

- [ ] Bug 修复
- [ ] 用户测试
- [ ] 更新文档
  - [ ] README 更新
  - [ ] 快捷键说明
  - [ ] 截图/GIF 演示
- [ ] 发布说明

---

## 5. 风险与应对

| 风险 | 影响 | 应对策略 |
|------|------|----------|
| 用户不适应新布局 | 中 | 提供设置选项，允许切换回旧版（临时） |
| 性能问题（大量 Examples） | 高 | Phase 4 重点优化，必要时虚拟滚动 |
| 移动端体验不佳 | 中 | 单独设计移动端布局，非简单缩放 |
| 与现有扩展冲突 | 低 | 充分的回归测试 |

---

## 6. 关联文件

### 6.1 需修改的现有文件

```
static/js/components/shared/ModelModal.js      # 完全重构
static/js/components/shared/showcase/          # 迁移至新目录
static/css/components/lora-modal/              # 样式重写
static/css/components/modal/_base.css          # Overlay 样式调整
```

### 6.2 参考资源

- [Midjourney Explore](https://www.midjourney.com/explore) - 交互参考
- [Pinterest Pin View](https://www.pinterest.com) - 布局参考
- [AGENTS.md](/AGENTS.md) - 项目代码规范

---

## 7. Checklist

### 7.1 启动前

- [ ] 创建 feature branch: `feature/model-modal-redesign`
- [ ] 设置开发环境
- [ ] 准备测试数据集（多种 Model 类型）

### 7.2 每个 Phase 完成时

- [ ] 代码审查
- [ ] 功能测试
- [ ] 更新本文档状态

### 7.3 发布前

- [ ] 完整回归测试
- [ ] 更新 CHANGELOG
- [ ] 更新版本号

---

## 8. 附录

### 8.1 命名规范

| 类型 | 规范 | 示例 |
|------|------|------|
| 文件 | kebab-case | `thumbnail-rail.js` |
| 组件 | PascalCase | `ThumbnailRail` |
| CSS 类 | BEM | `.thumbnail-rail__item--active` |
| 变量 | camelCase | `currentExampleIndex` |

### 8.2 颜色规范

使用现有 CSS 变量，不引入新颜色：

```css
--lora-accent: #4299e1;
--lora-accent-l: 60%;
--lora-accent-c: 0.2;
--lora-accent-h: 250;
--lora-surface: var(--card-bg);
--lora-border: var(--border-color);
```

---

*Last Updated: 2026-02-06*