7.8 KiB

Raw Blame History

RFC 133: 预览信息面板组件

元数据

状态: 已实施
创建日期: 2026-01-28
实施日期: 2026-01-28
作者: Kiro AI
类型: 新功能

概述

为 SingleViewPlayer 组件创建可展开的信息面板，支持分镜、角色、场景、道具、实拍等多种类型的详细信息展示和编辑。

背景

现状

当前 SingleViewPlayer 组件的信息浮层功能有限：

仅显示标题和描述
无交互功能
无法展示详细信息
不支持编辑

问题

用户无法查看完整的分镜/资源详细信息
无法在预览界面直接编辑信息
不同类型的内容需要不同的字段展示
信息展示不够直观和美观

目标

创建独立的 PreviewInfoPanel 组件
支持展开/收起动画
支持 5 种类型的内容展示
支持编辑模式
使用纯 CSS 动画，无需额外依赖

设计方案

组件架构

PreviewInfoPanel
├── 收起状态（默认）
│   ├── 标题（支持多状态）
│   ├── 描述（1行截断）
│   └── 展开按钮
└── 展开状态
    ├── 完整标题和描述
    ├── 详细字段（根据类型）
    ├── 编辑按钮
    └── 收起按钮

视觉设计

收起状态：

高度：80px
背景：bg-linear-to-t from-black/80 to-transparent
定位：absolute bottom-0 left-0 right-0
内容：标题 + 描述（1行）

展开状态：

高度：撑满图片容器（absolute top-0 bottom-0）
背景：bg-black/90 backdrop-blur-xl
内容：完整信息 + 可滚动
编辑模式：表单字段 + 保存/取消按钮

动画：

transition: all 300ms ease-out

数据类型

// 分镜数据
interface StoryboardData {
  shotNumber: string;      // 镜号
  title: string;           // 标题
  description: string;     // 内容描述
  shotSize?: string;       // 景别
  cameraMovement?: string; // 运镜
  dialogue?: string;       // 对白
}

// 角色数据
interface CharacterData {
  name: string;            // 角色名称
  costume?: string;        // 装扮
  gender?: string;         // 性别
  age?: string;            // 年龄
  occupation?: string;     // 职业
  roleType?: string;       // 主角类型
  personality?: string;    // 性格
  appearance?: string;     // 外貌特征
  voiceModel?: string;     // 声音模型
  description?: string;    // 简介
}

// 场景数据
interface SceneData {
  name: string;                // 场景名称
  setting?: string;            // 布景
  locationType?: string;       // 场景类型
  timeOfDay?: string;          // 时间
  weather?: string;            // 天气
  atmosphere?: string;         // 氛围
  realWorldLocation?: string;  // 现实取景地
  description?: string;        // 简介
}

// 道具数据
interface PropData {
  name: string;          // 道具名称
  status?: string;       // 状态
  propType?: string;     // 道具类型
  usage?: string;        // 用途
  quantity?: number;     // 数量
  size?: string;         // 尺寸
  description?: string;  // 简介
}

// 实拍数据
interface FootageData {
  name: string;          // 实拍名称
  duration?: string;     // 时长
  format?: string;       // 格式
  description?: string;  // 简介
}

组件接口

interface PreviewInfoPanelProps {
  type: 'storyboard' | 'character' | 'scene' | 'prop' | 'footage';
  data: PreviewData;
  onUpdate?: (data: PreviewData) => void;
}

实施细节

1. 组件创建

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

核心功能：

展开/收起状态管理
编辑模式切换
表单数据处理
类型化内容渲染

2. 动画实现

使用纯 CSS transition：

className={cn(
  'absolute left-0 right-0 bottom-0 transition-all duration-300 ease-out',
  isExpanded ? 'top-0' : 'h-20'
)}

3. 内容渲染

根据 type 属性渲染不同的字段：

renderStoryboardFields() - 分镜信息
renderCharacterFields() - 角色信息
renderSceneFields() - 场景信息
renderPropFields() - 道具信息
renderFootageFields() - 实拍信息

4. 编辑模式

点击编辑按钮激活编辑模式
表单字段使用 Input/Textarea/Select 组件
保存时调用 onUpdate 回调
取消时恢复原始数据

5. 集成到 SingleViewPlayer

<PreviewInfoPanel
  type={currentItem.type || 'storyboard'}
  data={{
    shotNumber: currentItem.shotNumber || '',
    title: currentItem.title,
    description: currentItem.description,
    // ... 其他字段
  }}
  onUpdate={(data) => {
    console.log('更新信息:', data);
    // TODO: 调用实际的更新 API
  }}
/>

技术选型

动画方案

选择: 纯 CSS Transition

理由：

✅ 零依赖，不增加包体积
✅ 性能优秀
✅ 满足需求（简单的展开/收起）
✅ 符合项目现有技术栈

备选: Framer Motion

❌ 需要安装依赖（~60KB）
✅ 动画控制更灵活
⚠️ 对当前需求来说过度设计

UI 组件

使用项目现有的 shadcn/ui 组件：

Input - 文本输入
Textarea - 多行文本
Select - 下拉选择
Button - 按钮
ScrollArea - 滚动区域

影响范围

修改的文件

client/src/components/features/preview/SingleViewPlayer.tsx
- 导入 PreviewInfoPanel 组件
- 替换原有信息浮层
- 扩展 StoryboardItem 接口
client/src/components/features/preview/PreviewInfoPanel.tsx (新建)
- 完整的信息面板组件实现

类型定义更新

扩展 StoryboardItem 接口：

interface StoryboardItem {
  id: string;
  title: string;
  description: string;
  thumbnailUrl: string;
  // 新增字段
  shotNumber?: string;
  shotSize?: string;
  cameraMovement?: string;
  dialogue?: string;
  type?: 'storyboard' | 'character' | 'scene' | 'prop' | 'footage';
}

测试计划

功能测试

展开/收起动画
- 点击按钮正常展开
- 点击按钮正常收起
- 动画流畅无卡顿
内容展示
- 分镜信息正确显示
- 角色信息正确显示
- 场景信息正确显示
- 道具信息正确显示
- 实拍信息正确显示
编辑模式
- 点击编辑按钮进入编辑模式
- 表单字段可正常输入
- 保存后数据更新
- 取消后恢复原始数据
响应式
- 不同屏幕尺寸下正常显示
- 滚动功能正常

性能测试

动画性能（60fps）
大量字段时的渲染性能
编辑模式切换性能

后续优化

数据持久化
- 集成后端 API
- 实现自动保存
- 添加加载状态
增强功能
- 支持快捷键（Esc 关闭、Enter 保存）
- 添加字段验证
- 支持撤销/重做
视觉优化
- 添加微动画
- 优化字段布局
- 支持主题切换
可访问性
- 键盘导航支持
- 屏幕阅读器支持
- ARIA 属性完善

风险评估

低风险

✅ 使用现有技术栈
✅ 独立组件，不影响其他功能
✅ 纯 CSS 动画，兼容性好

需要注意

⚠️ 不同类型的字段较多，需要仔细测试
⚠️ 编辑模式的数据同步需要处理好
⚠️ 后续需要集成后端 API

参考资料

ResourceProfileTab 组件 - 字段展示参考
Tailwind CSS Transitions
React Hook Form - 未来可能的表单优化方案

总结

PreviewInfoPanel 组件为预览界面提供了强大的信息展示和编辑能力，通过纯 CSS 动画实现流畅的交互体验，支持多种类型的内容展示，为用户提供了更好的使用体验。

7.8 KiB Raw Blame History