ComfyUI-Lora-Manager/docs/plan/model-modal-redesign.md

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 架构

/* 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 - 交互参考
• Pinterest Pin View - 布局参考
• 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 变量，不引入新颜色：

--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