# 时间轴分镜时长编辑器功能

**日期**: 2026-01-28  
**类型**: Feature (功能新增)  
**影响范围**: 时间轴分镜轨道

## 📋 变更概述

在时间轴分镜轨道的分镜块中添加了**可点击的时长标签**，用户可以快速编辑分镜时长，无需手动拖拽调整右边界。

## ✨ 新增功能

### 1. 时长标签可点击
- 分镜块右侧显示当前时长（如 `5.0s`），采用等宽字体 (`font-mono`)
- Hover 时高亮提示可点击状态
- 位于更多菜单按钮之前

### 2. Popover 时长编辑器
- 点击时长标签弹出紧凑型 Popover（宽度 32，128px）
- 包含数字输入框，支持小数输入（精度 0.1s）
- 自动聚焦并全选当前值，方便快速修改
- 实时验证：最小时长 0.5s
- 操作提示：Enter 确认 / Esc 取消

### 3. 快捷操作
- **Enter**: 应用新时长并关闭 Popover
- **Esc**: 取消编辑并关闭 Popover
- **失焦**: 自动应用新时长（延迟 150ms）

## 🎨 设计亮点

### 视觉风格
- **时长标签**:
  - 默认: `text-white/70`, `font-mono`, `text-[11px]`
  - Hover: `text-white/90` + `bg-white/10` + `rounded` + `px-1`
  - 焦点: `ring-1 ring-white/30`

- **Popover**:
  - 紧凑型设计 (`w-32`)
  - 对齐方式: `align="end"` (右对齐)
  - 位置: `side="top"` (上方弹出，避免遮挡下方内容)
  - 使用统一主题变量: `bg-bg-overlay`, `border-border-base`

### 交互细节
- 所有交互元素阻止事件冒泡，避免触发分镜块拖拽
- 输入框支持 `type="number"`, `step="0.1"`, `min={minDuration}`
- 错误提示显示为红色文字 (`text-error`)
- 禁用状态: `opacity-50` + `cursor-not-allowed`

## 📁 文件变更

### 新增文件
1. **`client/src/components/features/timeline/DurationEditor.tsx`**
   - 时长编辑器组件
   - Props:
     - `duration: number` - 当前时长（秒）
     - `minDuration?: number` - 最小时长（默认 0.5s）
     - `onDurationChange: (newDuration: number) => void` - 时长变化回调
     - `disabled?: boolean` - 是否禁用

### 修改文件
2. **`client/src/components/features/timeline/TimelineItem.tsx`**
   - 导入 `DurationEditor` 组件
   - 在分镜块右侧集成时长编辑器
   - 仅在分镜轨道 (`trackType === 'storyboard'`) 且可调整 (`onResizeRight`) 时显示
   - 时长变化后调用 `onResizeRight` 和 `onDragEnd` 持久化更改

## 🔧 技术实现

### 核心逻辑
```typescript
// 时长变化处理
onDurationChange={(newDuration) => {
  const newEndTime = startTime + newDuration;
  onResizeRight(id, newEndTime);
  onDragEnd?.(id); // 触发持久化
}}
```

### 验证规则
- 输入必须为有效数字
- 时长 >= `minDuration` (默认 0.5s)
- 超出范围显示错误提示

### 状态管理
- 使用 `useState` 管理 Popover 开关状态
- 使用 `useRef` 存储输入框引用
- 通过 `useEffect` 同步外部时长变化

## 🎯 用户价值

1. **效率提升**: 直接输入时长数值，比拖拽调整更精确、更快速
2. **减少操作**: 无需在属性面板中寻找时长字段
3. **即时反馈**: 在时间轴上直接看到时长变化，符合用户心智模型
4. **键盘友好**: 支持 Enter/Esc 快捷键，适合专业用户

## 🧪 测试建议

### 功能测试
- [ ] 点击时长标签正常打开 Popover
- [ ] 输入新时长按 Enter 确认，分镜块宽度同步更新
- [ ] 按 Esc 取消编辑，时长保持不变
- [ ] 点击 Popover 外部关闭，新时长应用
- [ ] 输入小于 0.5s 的值显示错误提示

### 边界测试
- [ ] 分镜块宽度 < 10% 时不显示时长标签
- [ ] 拖拽分镜时 Popover 自动关闭
- [ ] 锁定轨道时时长编辑器禁用
- [ ] 输入非数字显示错误提示

### 兼容性测试
- [ ] 非分镜轨道仍显示原有时长文字
- [ ] 与更多菜单按钮布局正确（间距 4px）
- [ ] 不影响分镜块的拖拽和调整功能

## 📊 性能影响

- **组件大小**: +5KB (DurationEditor 组件)
- **渲染性能**: 使用 `memo` 优化，无明显影响
- **交互延迟**: 失焦延迟 150ms，确保点击事件正常触发

## 🔮 后续优化

1. **增量调整**: 添加 ±0.5s / ±1s 快捷按钮（可选方案2）
2. **批量编辑**: 选中多个分镜时统一调整时长
3. **智能建议**: 根据视频素材时长自动推荐分镜时长
4. **历史记录**: 支持 Undo/Redo 时长变更

## 🔗 相关文档

- [TimelineItem 组件文档](../components/features/timeline/TimelineItem.md)
- [时间轴性能优化](./2026-01-28-timeline-performance-optimization.md)
- [UI/UX 设计规范](./.cursor/commands/ui-ux-pro-max.md)

---

**实现者**: AI Assistant  
**审核者**: _待审核_