docs/v1.0/client/changelogs/2026-02-09-preview-info-panel-voice-refactor.md

Changelog - PreviewInfoPanel 重构与标签音色配置

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

变更概述

重构 PreviewInfoPanel 组件，将单一详情页改为“详情 + 标签”双栏布局。并将角色的音色配置逻辑从角色详情移至标签（装扮）列表，实现了“不同装扮可配置不同音色”的需求。

技术实现

1. 数据结构扩展

• 文件: client/src/components/features/preview/types.ts
• 变更: 扩展 ResourceTag 接口，增加音色相关字段：

  export interface ResourceTag {
    // ...
    voiceProvider?: string;
    voiceModelId?: string;
    voiceSampleUrl?: string; // 用于试听
  }
  

2. UI 重构 (PreviewInfoPanel)

• 文件: client/src/components/features/preview/PreviewInfoPanel.tsx
• 布局调整:
  • 使用 CSS Grid 实现双栏布局：左侧宽栏显示详细信息，右侧窄栏（380px）显示标签列表。
  • 移除了左侧 renderCharacterFields 中的音色配置区域。
• 功能增强:
  • 在右侧标签列表中，针对 character 类型的资源，每个标签卡片增加音色配置区域。
  • 支持编辑模式下输入 voiceModelId 和 voiceSampleUrl。
  • 非编辑模式下显示音色 ID，并提供播放按钮（预留 onVoicePlay 接口）。

3. 逻辑更新

• 文件: client/src/components/features/preview/hooks/usePreviewActions.ts
• 变更: 更新 handleUpdateTag 函数，支持接收 voiceConfig 参数，并将音色信息保存到资源的 metadata.tags 中。
• 文件: client/src/components/features/preview/SingleViewPlayer.tsx
• 变更: 更新 SingleViewPlayerProps 接口，同步 onUpdateTag 的签名变更。

影响范围

• PreviewInfoPanel 组件结构完全改变。
• ResourceTag 数据结构变更（向下兼容，新增字段可选）。
• SingleViewPlayer 及其父组件（PreviewPanel）的 Props 传递。

后续计划

1. 音色播放支持: 当前 onVoicePlay 仅支持播放当前 Item 的默认音色。需升级 useMediaPlayback 以支持播放特定 Tag 的 voiceSampleUrl。
2. 后端支持: 确保后端 API 正确存储和返回 metadata 中的音色字段（目前前端已实现透传）。