QQMusic项目功能总结
一、核心功能分类
（一）界面交互功能
| 功能模块 | 实现方式 | 使用类（自定义/Qt库） | 核心类说明 |
|---|---|---|---|
| 窗口布局 | Head区（图标、搜索框、控制按钮）+ Body区（左侧功能栏+右侧页面区），QStackedWidget管理6个页面 | Qt库（QWidget、QStackedWidget、QHBoxLayout等） | |
| 按钮交互 | 左侧BtForm按钮带图标、文本和动画效果，点击切换页面，悬停/点击颜色变化 | 自定义类（BtForm） | 继承QWidget 属性：id（页面索引） 函数：setIcon（设置图标/文本/ID）、clearBg（清除样式）、showAnimal（显示动画） 功能：通过QPropertyAnimation实现右侧竖条动画，点击时发射信号切换QStackedWidget页面 |
| 推荐页轮播 | 左右翻页按钮切换推荐内容，鼠标悬停元素上移动画 | 自定义类（RecBox、RecBoxItem） | RecBox继承QWidget，管理RecBoxItem列表；RecBoxItem继承QWidget，处理鼠标事件 函数：initRecBoxUi（初始化布局）、createRecBoxItem（创建推荐项） 流程：解析QJsonArray数据，动态生成RecBoxItem，通过QPropertyAnimation实现悬停位移动画 |
| 歌词显示 | 点击“词”按钮弹出歌词页，带动画显示/隐藏，歌词随时间滚动 | 自定义类（LrcPage） | 继承QWidget 函数：parseLrc（解析LRC文件）、showLrcWord（同步歌词） 流程：解析LRC文件生成时间-歌词映射，通过QPropertyAnimation实现页面上下滑动动画，根据播放时间更新当前歌词高亮 |
（二）音乐播放功能
| 功能模块 | 实现方式 | 使用类（自定义/Qt库） | 核心类说明 |
|---|---|---|---|
| 基础播放控制 | 播放/暂停、上一曲/下一曲、音量调节、Seek进度条 | Qt库（QMediaPlayer、QMediaPlaylist） | QMediaPlayer处理播放逻辑，QMediaPlaylist管理播放列表 函数：setPlaylist（设置播放列表）、setVolume（调节音量）、setPosition（Seek定位） 信号槽：关联stateChanged（更新播放按钮图标）、positionChanged（同步进度和时间） |
| 播放模式 | 随机、单曲循环、列表循环 | Qt库（QMediaPlaylist） | 枚举PlaybackMode设置模式，通过信号playbackModeChanged更新界面图标 |
| 歌词同步 | 解析LRC文件，按时间戳显示当前歌词 | 自定义类（LrcPage）+ Qt库 | 解析LRC文件生成LyricLine结构体（时间+歌词），通过QMediaPlayer的positionChanged信号触发歌词更新 |
（三）数据管理与持久化
| 功能模块 | 实现方式 | 使用类（自定义/Qt库） | 核心类说明 |
|---|---|---|---|
| 歌曲信息管理 | Music类封装元数据（名称、歌手、专辑、路径、收藏/历史标记） | 自定义类（Music） | 继承QObject 属性：musicId（UUID唯一标识）、isLike、isHistory 函数：parseMediaMetaData（解析元数据）、insertMusicToDB（写入数据库） 流程：通过QMediaPlayer解析音频文件元数据，存储到Music对象，通过MusicList管理列表 |
| 数据库持久化 | SQLite存储歌曲信息、收藏和播放记录 | Qt库（QSqlDatabase、QSqlQuery） | 创建musicInfo表，程序启动时读取数据库恢复数据，退出时写入最新状态 SQL语句：CREATE TABLE（建表）、INSERT/UPDATE（写入）、SELECT（查询） |
（四）自定义控件汇总
| 控件名称 | 继承类 | 核心属性 | 关键函数 | 功能描述 |
|---|---|---|---|---|
| BtForm | QWidget | id（页面索引） | setIcon()、clearBg()、showAnimal() | 左侧功能按钮，带图标、文本和动画效果，点击切换页面，通过信号槽与QStackedWidget联动 |
| RecBox | QWidget | row（行数）、col（列数） | initRecBoxUi()、createRecBoxItem() | 推荐页轮播容器，管理RecBoxItem，支持左右翻页和分组显示 |
| CommonPage | QWidget | pageType（页面类型：收藏/本地/历史） | setCommonPageUI()、reFresh() | 通用页面模板，统一管理“我喜欢”“本地下载”“最近播放”页面，通过QListWidget显示歌曲列表 |
| ListItemBox | QWidget | isLike（收藏状态） | setMusicName()、setLikeIcon() | 列表项控件，显示歌曲详情和收藏图标，点击收藏按钮发射信号更新Music对象 |
| MusicSlider | QWidget | currentPos（当前进度） | mousePressEvent()、mouseMoveEvent() | 自定义进度条，支持鼠标拖拽Seek，通过信号同步播放位置 |
| VolumeTool | QWidget | isMuted（静音状态）、volumeRatio（音量比例） | eventFilter()、setVolume() | 音量调节弹窗，带静音按钮和滑动条，通过事件过滤器处理鼠标操作，发射信号更新音量 |
（五）技术实现流程
- 页面切换流程
- 点击左侧BtForm按钮，触发click信号并传递页面ID
- QQMusic接收信号后，遍历所有BtForm按钮，清除非当前按钮的样式和动画
- 通过QStackedWidget.setCurrentIndex()显示对应页面，调用updateBtFormAnimal()更新当前按钮动画
- 音乐播放流程
- 双击列表项或点击“播放全部”，触发CommonPage发射playAll或playMusicByIndex信号
- QQMusic根据信号获取当前页面歌曲列表，清空QMediaPlaylist并重新添加歌曲URL
- 调用QMediaPlayer.play()开始播放，关联stateChanged信号更新播放按钮图标，positionChanged同步进度和时间
- 数据持久化流程
- 写入数据库：程序退出时，MusicList遍历所有Music对象，检测是否存在，存在则更新isLike和isHistory，不存在则插入新记录
- 读取数据库：程序启动时，从musicInfo表查询所有记录，生成Music对象并添加到MusicList，更新各CommonPage显示
- 歌词同步流程
- 播放歌曲时，QMediaPlayer触发metaDataAvailableChanged信号，获取当前歌曲LRC路径
- LrcPage.parseLrc()解析LRC文件，生成时间-歌词列表
- 监听QMediaPlayer.positionChanged信号，计算当前时间对应的歌词行，更新界面显示并高亮当前歌词
（六）未实现与扩展功能
| 功能 | 状态 | 后续计划 |
|---|---|---|
| 皮肤更换 | 暂未实现 | 通过QSS动态切换样式表，支持自定义背景颜色或图片 |
| 网络模块 | 暂未实现 | 添加网络请求接口，实现在线歌曲搜索、推荐和歌词下载 |
| 单实例运行 | 已实现 | 通过QSharedMemory检测共享内存，防止程序多开 |
