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檢測共享內存，防止程序多開 |
