docs/v1.0/client/changelogs/2026-02-09-character-voice-preview.md

Changelog - 角色音色预览 UI

日期: 2026-02-09
类型: 功能增强 (UI Only)
模块: 前端 - PreviewPanel

变更概述

在 SingleViewPlayer 组件的底部信息条中，为角色资源类型添加音色播放按钮 UI。

技术实现

修改文件

• client/src/components/features/preview/SingleViewPlayer.tsx

实现细节

1. 导入图标

   • 新增 Volume2 图标 (from lucide-react)

2. 音色播放按钮

   • 位置: 底部信息条左侧，标题和标签之后
   • 显示条件: 仅当 currentItem?.type === 'character' 时显示
   • 交互逻辑:
     • 点击调用 playbackState.handleVoicePlay()
     • 使用 e.stopPropagation() 防止触发父级的面板展开
   • 视觉反馈:
     • 默认状态: 半透明品牌色背景 + 细边框
     • Hover 状态: 加深背景色和边框
     • 播放中: 脉冲动画 (animate-pulse)
   • 工具提示: 根据播放状态显示 "播放角色音色" 或 "停止播放音色"

3. 样式设计

   // 圆形按钮，6x6 尺寸
   'w-6 h-6 rounded-full'
   // 品牌色调
   'bg-brand-default/10 hover:bg-brand-default/20'
   'ring-1 ring-brand-default/20 hover:ring-brand-default/40'
   // 播放状态动画
   playbackState.isVoicePlaying && 'bg-brand-default/20 ring-brand-default/40 animate-pulse'
   

4. 复用现有逻辑

   • 使用 useMediaPlayback Hook 管理播放状态
   • 音频 URL 来源: currentItem?.voiceSampleUrl (由 usePreviewData 提供)

当前状态

✅ UI 实现完成
⚠️ 功能待实现（依赖后续工作）:

• 数据库添加 voice_model、voice_sample_url 字段
• 后端 API 返回音色数据
• 前端数据映射和真实播放

视觉效果

┌─────────────────────────────────────────────────┐
│ [▼] 李明 [便装] [🔊]  [详情] [历史] [替换]    │
│     ↑     ↑     ↑                              │
│   标题   标签  音色按钮                         │
└─────────────────────────────────────────────────┘

相关链接

• 父组件: SingleViewPlayer.tsx
• Hook: useMediaPlayback.ts
• 数据源: usePreviewData.ts

后续任务

1. 数据库迁移: 添加音色字段到 project_characters 表
2. 后端: 更新 CharacterDetailResponse Schema
3. 前端: 映射 voice_sample_url 到 StoryboardItem
4. 测试: 端到端播放流程验证