docs/v1.0/client/changelogs/2026-02-03-video-generation-precheck-floating-layer.md

视频生成预检浮层重构

日期: 2026-02-03 类型: 功能优化 影响范围: 前端 - 分镜看板、预览面板

变更概述

将视频生成预检功能从 Dialog 弹窗改造为浮层组件，在点击视频轨道未生成视频的元素块时，在中间预览区域上方显示定位浮层。

主要变更

1. GenerationPrecheck 组件重构

文件: client/src/components/features/preview/GenerationPrecheck.tsx

• ✅ 移除 Dialog 和 DialogContent 依赖
• ✅ 改为使用固定定位的浮层 + 遮罩层实现
• ✅ 添加关闭按钮（X 图标）
• ✅ 添加 onClose 回调属性
• ✅ 使用 animate-in 动画效果（fade-in + zoom-in-95）
• ✅ 浮层居中显示，宽度 90vw（最大 4xl），高度 72vh

接口变更:

// 旧接口
interface GenerationPrecheckProps {
  open?: boolean;
  onOpenChange?: (open: boolean) => void;
  // ...
}

// 新接口
interface GenerationPrecheckProps {
  open?: boolean;
  onClose?: () => void;
  // ...
}

2. EditorStore 状态管理

文件: client/src/stores/editorStore.ts

新增状态：

• videoGenerationPrecheckOpen: boolean - 浮层显示状态
• videoGenerationPrecheckStoryboardId: string | null - 当前预检的分镜 ID

新增方法：

• openVideoGenerationPrecheck(storyboardId: string) - 打开预检浮层
• closeVideoGenerationPrecheck() - 关闭预检浮层

3. CenterArea 布局集成

文件: client/src/components/layout/CenterArea.tsx

• ✅ 导入 GenerationPrecheck 组件
• ✅ 导入 useStoryboards 和 useResources hooks
• ✅ 根据 videoGenerationPrecheckStoryboardId 查找对应分镜
• ✅ 在 PreviewPanel 同级渲染浮层组件
• ✅ 传递分镜数据、资源数据和关闭回调

4. StoryboardBoardTrack 点击事件

文件: client/src/components/features/storyboard-board/StoryboardBoardTrack.tsx

• ✅ 移除 VideoGenerationPopover 导入
• ✅ 导入 useEditorStore 获取 openVideoGenerationPrecheck 方法
• ✅ 为视频轨道占位块添加 onClick 事件
• ✅ 点击时调用 openVideoGenerationPrecheck(storyboardId)

5. 删除冗余组件

删除文件: client/src/components/features/storyboard-board/VideoGenerationPopover.tsx

原因：功能已被 GenerationPrecheck 浮层替代，避免代码重复。

技术细节

浮层定位方案

使用 CSS 固定定位实现全局浮层：

{/* 遮罩层 */}
<div className="fixed inset-0 bg-black/50 backdrop-blur-sm z-40" />

{/* 浮层内容 */}
<div className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 z-50">
  <GenerationPrecheckContent />
</div>

状态流转

1. 用户点击视频轨道占位块
2. 触发 openVideoGenerationPrecheck(storyboardId)
3. EditorStore 更新状态：videoGenerationPrecheckOpen = true
4. CenterArea 检测到状态变化，渲染浮层
5. 用户点击关闭按钮或遮罩层
6. 触发 closeVideoGenerationPrecheck()
7. 浮层隐藏

用户体验改进

优点

1. 更好的视觉层级: 浮层覆盖在预览区域上方，视觉焦点更集中
2. 更灵活的定位: 不受触发元素位置限制，始终居中显示
3. 更统一的交互: 移除了 Popover 和 Dialog 两种不同的交互方式
4. 更清晰的关闭方式: 提供明确的关闭按钮和遮罩层点击关闭

交互流程

分镜看板视频轨道
    ↓ 点击未生成视频的占位块
预览区域上方显示浮层
    ↓ 查看资源就绪状态
    ↓ 点击关闭按钮或遮罩层
浮层关闭

测试建议

功能测试

1. ✅ 点击视频轨道占位块，浮层正确显示
2. ✅ 浮层显示正确的分镜资源信息
3. ✅ 点击关闭按钮，浮层关闭
4. ✅ 点击遮罩层，浮层关闭
5. ✅ 浮层动画效果流畅

边界测试

1. ✅ 分镜无资源时，浮层正常显示
2. ✅ 快速切换不同分镜，浮层内容正确更新
3. ✅ 浮层打开时，背景内容不可交互

兼容性测试

1. ✅ TypeScript 类型检查通过
2. ✅ 不同屏幕尺寸下浮层正确居中
3. ✅ 浮层内容滚动正常

后续优化建议

1. 添加键盘快捷键: 支持 ESC 键关闭浮层
2. 添加操作按钮: 在浮层中添加"去定稿"、"立即生成"等操作按钮
3. 显示视频版本列表: 恢复底部视频版本缩略图列表功能
4. 添加加载状态: 分镜数据加载时显示骨架屏

相关文件

修改文件

• client/src/components/features/preview/GenerationPrecheck.tsx
• client/src/stores/editorStore.ts
• client/src/components/layout/CenterArea.tsx
• client/src/components/features/storyboard-board/StoryboardBoardTrack.tsx

删除文件

• client/src/components/features/storyboard-board/VideoGenerationPopover.tsx

版本信息

• 前端框架: React 19 + TypeScript
• 状态管理: Zustand
• UI 组件: shadcn/ui
• 动画: Tailwind CSS animate-in utilities