【QQMusic项目复习笔记——音乐管理模块详解】第四章

🌹 作者: 云小逸
🤟 个人主页: 云小逸的主页
🤟 motto: 要敢于一个人默默的面对自己，强大自己才是核心。不要等到什么都没有了，才下定决心去做。种一颗树，最好的时间是十年前，其次就是现在！学会自己和解，与过去和解，努力爱自己。希望春天来之前，我们一起面朝大海，春暖花开！

🥇 专栏:

• 动态规划
• C 语言
• C++
• Java 语言
• Linux 编程
• 算法
• 待续…

📚 前言

在QQMusic这样的音乐软件里，音乐管理模块可是非常重要的。它就像是一个大管家，负责把音乐从你的电脑里找出来，整理好，然后展示给你看，还能让你把喜欢的音乐收藏起来。这篇笔记会详细地给你讲解第4章的内容，把代码和逻辑结合起来，让你轻松理解怎么实现这么厉害的音乐管理功能。

一、音乐加载与筛选

1. 使用QFileDialog加载本地音乐

void QQMusic::on_addLocal_clicked() {QFileDialog fileDialog(this);fileDialog.setWindowTitle("添加本地音乐");fileDialog.setAcceptMode(QFileDialog::AcceptOpen); // 设置为打开文件模式fileDialog.setFileMode(QFileDialog::ExistingFiles); // 允许选择多个已存在的文件// 设置MIME过滤器，只显示音频文件QStringList mimeList;mimeList << "application/octet-stream"; // 通用二进制流（可根据需求细化为mp3、flac等）fileDialog.setMimeTypeFilters(mimeList);// 设置默认打开目录QDir dir(QDir::currentPath());dir.cdUp();QString musicPath = dir.path() + "/QQMusic/musics/";fileDialog.setDirectory(musicPath);// 显示对话框，获取用户选择的文件if (fileDialog.exec() == QFileDialog::Accepted) {QList<QUrl> urls = fileDialog.selectedUrls(); // 获取选中文件的URL列表musicList.addMusicByUrl(urls); // 交给MusicList处理ui->stackedWidget->setCurrentIndex(4); // 切换到本地音乐页面}
}

• 创建文件选择对话框：
  • 使用QFileDialog创建一个用于选择文件的对话框，将其作为当前QQMusic对象的子对象。
  • 通过setWindowTitle方法为对话框设置标题“添加本地音乐”，方便用户识别该对话框的用途。
• 设置对话框模式和文件选择规则：
  • 调用setAcceptMode方法，将对话框设置为打开文件模式，明确其功能是让用户选择要打开的文件。
  • 使用setFileMode方法，允许用户选择多个已经存在的文件，这样用户可以一次性添加多首本地音乐。
• 设置文件类型过滤器：
  • 创建一个QStringList类型的mimeList，并添加“application/octet - stream”（通用二进制流，可根据实际需求细化为mp3、flac等具体音频格式）。
  • 调用setMimeTypeFilters方法，将mimeList设置为对话框的MIME类型过滤器，确保用户只能看到和选择音频文件。
• 设置默认打开目录：
  • 获取当前工作目录，然后使用cdUp方法向上一级目录移动。
  • 拼接出一个音乐文件所在的默认目录路径musicPath，并通过setDirectory方法将其设置为对话框的默认打开目录，方便用户快速定位到音乐文件。
• 获取用户选择的文件并处理：
  • 调用exec方法显示对话框，当用户点击“确定”按钮（即返回值为QFileDialog::Accepted）时，获取用户选中文件的URL列表。
  • 将URL列表传递给MusicList的addMusicByUrl方法进行进一步处理。
  • 最后，使用ui->stackedWidget->setCurrentIndex(4)将界面切换到本地音乐页面，让用户可以查看刚添加的音乐。

2. MusicList类：音乐集合管理

// MusicList.h
#include <QVector>
#include <QUrl>
#include "music.h"class MusicList {
public:void addMusicByUrl(const QList<QUrl>& urls); // 从URL列表添加音乐iterator begin(); // 迭代器开始iterator end(); // 迭代器结束iterator findMusicById(const QString& musicId); // 通过UUID查找音乐
private:QVector<Music> musicList; // 存储Music对象QSet<QString> musicPaths; // 存储已加载的文件路径，避免重复加载
};// MusicList.cpp
void MusicList::addMusicByUrl(const QList<QUrl>& urls) {for (auto e : urls) {QString musicPath = e.toLocalFile();if (musicPaths.contains(musicPath)) continue; // 跳过已加载的文件musicPaths.insert(musicPath); // 记录路径防止重复QMimeDatabase mimeDB;QMimeType mimeType = mimeDB.mimeTypeForFile(musicPath);// 筛选支持的音频格式（mp3、flac等）if (mimeType.name() != "audio/mpeg" && mimeType.name() != "audio/flac") continue;Music music(e); // 创建Music对象，自动解析元数据musicList.push_back(music); // 添加到列表}
}

• 类的成员和功能概述：
  • MusicList类用于管理音乐集合，包含一个QVector<Music>类型的musicList成员，用于存储Music对象，以及一个QSet<QString>类型的musicPaths成员，用于记录已经加载过的音乐文件路径，避免重复加载。
  • 提供了addMusicByUrl方法用于从URL列表添加音乐，还提供了迭代器相关方法begin、end以及通过UUID查找音乐的findMusicById方法。
• 添加音乐的具体实现：
  • 在addMusicByUrl方法中，遍历传入的URL列表。
  • 将每个URL转换为本地文件路径musicPath，并检查musicPaths集合中是否已经包含该路径，如果包含则跳过该文件，避免重复添加。
  • 若路径未被记录，则将其插入到musicPaths集合中。
  • 使用QMimeDatabase和QMimeType来获取文件的MIME类型，筛选出支持的音频格式（如mp3、flac），若文件类型不符合要求则跳过。
  • 对于符合要求的文件，创建一个Music对象，该对象会自动解析音乐的元数据。
  • 最后将创建好的Music对象添加到musicList向量中。

3. Music类：单个音乐元数据封装

// Music.h
class Music {
public:Music(const QUrl& url); // 构造函数，自动解析元数据void parseMediaMetaData(); // 解析音乐元数据QString getLrcFilePath() const; // 获取对应的LRC歌词路径
private:QString musicId; // UUID，唯一标识音乐QString musicName, singerName, albumName; // 名称、歌手、专辑qint64 duration; // 时长（毫秒）QUrl musicUrl; // 文件路径bool isLike, isHistory; // 收藏状态、历史播放状态
};// Music.cpp
Music::Music(const QUrl& url) : musicUrl(url) {musicId = QUuid::createUuid().toString(); // 生成UUIDparseMediaMetaData(); // 解析元数据
}void Music::parseMediaMetaData() {QMediaPlayer player;player.setMedia(musicUrl);// 等待元数据加载完成while (!player.isMetaDataAvailable()) {QCoreApplication::processEvents(); // 处理事件循环，避免界面卡顿}// 提取元数据，默认值处理空数据musicName = player.metaData("Title").toString().trimmed() ?: "歌曲未知";singerName = player.metaData("Author").toStringList().join(",").trimmed() ?: "歌手未知";albumName = player.metaData("AlbumTitle").toString().trimmed() ?: "专辑名未知";duration = player.duration(); // 获取时长
}QString Music::getLrcFilePath() const {// 将音频文件后缀替换为.lrc，假设歌词文件同名QString path = musicUrl.toLocalFile();path.replace(".mp3", ".lrc").replace(".flac", ".lrc");return path;
}

• 类的成员和功能概述：
  • Music类用于封装单个音乐的元数据，包含音乐的唯一标识musicId、名称musicName、歌手singerName、专辑albumName、时长duration、文件路径musicUrl以及收藏状态isLike和历史播放状态isHistory。
  • 提供了构造函数Music(const QUrl& url)用于创建对象并自动解析元数据，parseMediaMetaData方法用于解析音乐元数据，getLrcFilePath方法用于获取对应的LRC歌词文件路径。
• 构造函数的实现：
  • 在构造函数中，将传入的URL赋值给musicUrl成员。
  • 使用QUuid::createUuid().toString()生成一个唯一的UUID作为musicId，确保每个音乐对象都有唯一标识。
  • 调用parseMediaMetaData方法解析音乐的元数据。
• 元数据解析方法：
  • 创建一个QMediaPlayer对象player，并将musicUrl设置为其播放媒体。
  • 使用while循环等待元数据加载完成，在等待过程中调用QCoreApplication::processEvents()处理事件循环，避免界面卡顿。
  • 从player中提取音乐的标题、作者、专辑名等元数据，使用trimmed方法去除字符串前后的空格，并使用空值合并运算符?:为可能为空的元数据设置默认值（如“歌曲未知”“歌手未知”“专辑名未知”）。
  • 通过player.duration()获取音乐的时长。
• 获取歌词文件路径方法：
  • 将musicUrl转换为本地文件路径path。
  • 使用replace方法将文件后缀.mp3和.flac替换为.lrc，假设歌词文件与音频文件同名，返回替换后的路径。

二、音乐分类与界面更新

1. CommonPage：通用页面模板

// CommonPage.h
enum PageType { LIKE_PAGE, LOCAL_PAGE, HISTORY_PAGE }; // 页面类型枚举class CommonPage : public QWidget {
public:void setMusicListType(PageType type); // 设置页面类型void reFresh(const MusicList& musicList); // 刷新页面显示
private:PageType pageType; // 当前页面类型QVector<QString> musicListOfPage; // 本页面的音乐ID列表QListWidget* pageMusicList; // 音乐列表控件
};// CommonPage.cpp
void CommonPage::setMusicListType(PageType type) {pageType = type; // 记录页面类型// 根据类型设置页面标题和背景switch (type) {case LIKE_PAGE: setCommonPageUI("我喜欢", ":/images/ilikebg.png"); break;case LOCAL_PAGE: setCommonPageUI("本地音乐", ":/images/localbg.png"); break;case HISTORY_PAGE: setCommonPageUI("最近播放", ":/images/recentbg.png"); break;}
}void CommonPage::reFresh(const MusicList& musicList) {pageMusicList->clear(); // 清空旧数据musicListOfPage.clear(); // 清空旧ID列表// 根据页面类型筛选音乐for (auto& music : musicList) {switch (pageType) {case LOCAL_PAGE: musicListOfPage.push_back(music.getMusicId()); // 本地页面直接添加所有break;case LIKE_PAGE: if (music.getIsLike()) musicListOfPage.push_back(music.getMusicId()); // 只添加收藏的break;case HISTORY_PAGE: if (music.getIsHistory()) musicListOfPage.push_back(music.getMusicId()); // 只添加历史播放的break;}}// 添加自定义控件ListItemBox到QListWidgetfor (auto musicId : musicListOfPage) {auto it = musicList.findMusicById(musicId);ListItemBox* item = new ListItemBox();item->setMusicName(it->getMusicName());item->setSinger(it->getSingerName());item->setLikeIcon(it->getIsLike()); // 设置收藏图标QListWidgetItem* listItem = new QListWidgetItem();listItem->setSizeHint(item->size());pageMusicList->setItemWidget(listItem, item);}
}

• 类的成员和功能概述：
  • CommonPage类是一个通用的页面模板，继承自QWidget。它使用枚举PageType来区分不同的页面类型（“我喜欢”“本地音乐”“最近播放”）。
  • 包含pageType成员记录当前页面类型，musicListOfPage存储本页面要显示的音乐ID列表，pageMusicList是用于显示音乐列表的控件。
  • 提供了setMusicListType方法用于设置页面类型并根据类型设置页面标题和背景，reFresh方法用于刷新页面显示。
• 设置页面类型的实现：
  • 在setMusicListType方法中，将传入的PageType类型参数赋值给pageType成员，记录当前页面类型。
  • 使用switch语句根据不同的页面类型调用setCommonPageUI方法设置页面的标题和背景图片。
• 刷新页面显示的实现：
  • 首先，清空pageMusicList控件中的旧数据和musicListOfPage中的旧ID列表。
  • 遍历MusicList中的所有音乐对象，根据pageType的值进行筛选：
    • 对于“本地音乐”页面，将所有音乐的ID添加到musicListOfPage中。
    • 对于“我喜欢”页面，只将收藏状态为true的音乐ID添加到musicListOfPage中。
    • 对于“最近播放”页面，只将历史播放状态为true的音乐ID添加到musicListOfPage中。
  • 遍历musicListOfPage中的音乐ID，通过findMusicById方法找到对应的音乐对象。
  • 创建一个ListItemBox自定义控件，设置其显示的音乐名称、歌手和收藏图标。
  • 创建一个QListWidgetItem，设置其大小提示为ListItemBox的大小。
  • 将ListItemBox设置为QListWidgetItem的自定义控件，并添加到pageMusicList中。

2. ListItemBox：音乐列表项控件

// ListItemBox.h
class ListItemBox : public QWidget {Q_OBJECT
public:void setMusicName(const QString& name); // 设置歌曲名称void setSinger(const QString& singer); // 设置歌手void setLikeIcon(bool isLike); // 设置收藏图标状态
signals:void setIsLike(bool isLike, QString musicId); // 收藏状态改变信号
private:bool isLike; // 当前收藏状态QPushButton* likeBtn; // 收藏按钮QString musicId; // 关联的音乐ID
};// ListItemBox.cpp
void ListItemBox::setLikeIcon(bool isLike) {this->isLike = isLike;likeBtn->setIcon(isLike ? QIcon(":/images/like_2.png") : QIcon(":/images/like_3.png")); // 切换图标
}// 点击收藏按钮时触发
void ListItemBox::on_likeBtn_clicked() {isLike = !isLike; // 取反状态emit setIsLike(isLike, musicId); // 发射信号，携带新状态和音乐ID
}

• 类的成员和功能概述：
  • ListItemBox类继承自QWidget，用于显示单个音乐列表项的信息。
  • 包含isLike成员记录当前音乐的收藏状态，likeBtn是收藏按钮，musicId是关联的音乐ID。
  • 提供了setMusicName、setSinger和setLikeIcon方法用于设置显示的音乐名称、歌手和收藏图标状态，还定义了一个信号setIsLike用于在收藏状态改变时发出通知。
• 设置收藏图标状态的实现：
  • 在setLikeIcon方法中，将传入的isLike值赋值给isLike成员。
  • 根据isLike的值，为likeBtn设置不同的图标（like_2.png表示已收藏，like_3.png表示未收藏）。
• 处理收藏按钮点击事件的实现：
  • 在on_likeBtn_clicked方法中，当用户点击收藏按钮时，将isLike状态取反。
  • 调用emit关键字发射setIsLike信号，携带新的收藏状态和关联的音乐ID，通知其他部分更新数据。

三、音乐收藏与持久化

1. 收藏逻辑：界面与数据同步

// QQMusic.cpp
void QQMusic::onUpdateLikeMusic(bool isLike, QString musicId) {auto it = musicList.findMusicById(musicId); // 查找对应的Music对象if (it != musicList.end()) {it->setIsLike(isLike); // 更新本地状态}// 刷新所有相关页面（我喜欢、本地、历史播放）ui->likePage->reFresh(musicList);ui->localPage->reFresh(musicList);ui->recentPage->reFresh(musicList);
}// CommonPage.cpp（信号连接）
connect(ui->pageMusicList, &QListWidget::itemClicked, [=](QListWidgetItem* item) {ListItemBox* listItem = static_cast<ListItemBox*>(pageMusicList->itemWidget(item));connect(listItem, &ListItemBox::setIsLike, this, [=](bool isLike, QString musicId) {emit updateLikeMusic(isLike, musicId); // 传递给QQMusic处理});
});

• 收藏状态更新的实现：
  • 在QQMusic类的onUpdateLikeMusic方法中，接收收藏状态isLike和音乐IDmusicId作为参数。
  • 使用findMusicById方法在musicList中查找对应的Music对象。
  • 如果找到该对象，则调用其setIsLike方法更新本地的收藏状态。
  • 调用所有相关页面（“我喜欢”“本地音乐”“最近播放”）的reFresh方法，刷新页面显示，确保界面上的收藏状态与数据一致。
• 信号传递的实现：
  • 在CommonPage类中，通过connect函数连接pageMusicList的itemClicked信号。
  • 当用户点击列表项时，将列表项对应的ListItemBox控件转换为正确的类型。
  • 再通过connect函数连接ListItemBox的setIsLike信号，当收藏状态改变时，将新的状态和音乐ID通过updateLikeMusic信号传递给QQMusic类进行处理。

2. 数据库持久化：SQLite存储音乐信息

// 建表语句（MusicInfo表）
CREATE TABLE IF NOT EXISTS musicInfo (id INTEGER PRIMARY KEY AUTOINCREMENT,musicId VARCHAR(200) UNIQUE, // UUID，唯一标识musicName VARCHAR(50),musicSinger VARCHAR(50),albumName VARCHAR(50),duration BIGINT, // 时长（毫秒）musicUrl VARCHAR(256), // 文件路径isLike INTEGER, // 0未收藏，1已收藏isHistory INTEGER // 0未播放，1已播放
);// Music.cpp 插入/更新数据库
void Music::insertMusicToDB() {QSqlQuery query;// 检测是否已存在query.prepare("SELECT EXISTS (SELECT 1 FROM musicInfo WHERE musicId = ?)");query.addBindValue(musicId);query.exec();query.next();bool isExists = query.value(0).toBool();if (isExists) {// 更新收藏/历史状态query.prepare("UPDATE musicInfo SET isLike = ?, isHistory = ? WHERE musicId = ?");query.addBindValue(isLike ? 1 : 0);query.addBindValue(isHistory ? 1 : 0);query.addBindValue(musicId);} else {// 插入新记录query.prepare("INSERT INTO musicInfo (musicId, musicName, musicSinger, albumName, musicUrl, duration, isLike, isHistory) VALUES (?, ?, ?, ?, ?, ?, ?, ?)");query.addBindValue(musicId);query.addBindValue(musicName);query.addBindValue(musicSinger);// 其他字段依次绑定...}query.exec();
}

• 数据库表结构设计：
  • 创建一个名为musicInfo的表，使用id作为自增的主键，确保每条记录有唯一标识。
  • 使用musicId作为UUID，唯一标识每首音乐，防止重复记录。
  • 存储音乐的名称、歌手、专辑名、时长、文件路径、收藏状态和历史播放状态。
• 插入/更新数据库的实现：
  • 在Music类的insertMusicToDB方法中，创建一个QSqlQuery对象用于执行SQL语句。
  • 首先执行一个查询语句，检测当前音乐记录是否已经存在于数据库中。
  • 如果记录已经存在，则执行UPDATE语句更新收藏和历史播放状态。
  • 如果记录不存在，则执行INSERT语句插入一条新的记录，将音乐的各项信息绑定到相应的参数位置。
  • 最后执行SQL语句完成插入或更新操作。

四、CommonPage显示不足处理

功能概述

这部分主要是针对CommonPage页面在显示音乐列表时可能会出现的各种显示问题进行优化。在显示音乐信息时，可能会存在文本对齐不整齐、显示有延迟、滚动条样式不美观等情况。通过对这些问题的处理，可以确保界面显示的一致性和美观性，提升用户的视觉体验。

核心处理内容及实现方法

a. 歌曲作者对齐处理

// 在Music类解析元数据时处理空值和空格
if (musicName.isEmpty()) {// 从文件名解析并去除空格musicName = fileName.mid(0, index).trimmed(); 
}
if (singerName.isEmpty()) {singerName = fileName.mid(index+1, fileName.indexOf('.')-index-1).trimmed(); 
}

• 问题分析：在解析音乐元数据时，如果歌曲名称、歌手或者专辑信息缺失，直接显示这些信息会导致界面上的文本出现错位，比如前后有多余的空格。
• 解决步骤：
  • 检查musicName是否为空，如果为空，则从文件名中提取歌曲名称部分，并使用trimmed方法去除前后的空格。
  • 检查singerName是否为空，如果为空，则从文件名中提取歌手名称部分，并使用trimmed方法去除前后的空格。

b. 显示延迟问题

void CommonPage::reFresh(MusicList &musicList) {// ... 其他逻辑 ...repaint(); // 强制界面重绘，确保更新显示
}

• 问题分析：当更新音乐列表之后，界面可能不会马上刷新，需要手动触发重绘才能看到更新后的内容。
• 解决步骤：在CommonPage类的reFresh方法中，在完成其他更新逻辑后，调用repaint方法强制界面进行重绘，确保更新后的内容能够实时显示。

c. 移除QListWidget水平滚动条

CommonPage::CommonPage(QWidget *parent) : QWidget(parent), ui(new Ui::CommonPage) {ui->setupUi(this);ui->pageMusicList->setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff); // 禁用水平滚动条
}

• 目的分析：一般情况下，歌曲信息不会超出列表的宽度，显示水平滚动条会影响界面的简洁性，因此需要将其隐藏。
• 解决步骤：在CommonPage类的构造函数中，调用setHorizontalScrollBarPolicy方法，将水平滚动条的策略设置为Qt::ScrollBarAlwaysOff，即始终关闭水平滚动条。

d. QListWidget选中项背景色设置

#pageMusicList::item:selected {background-color: #EFEFEF; // 浅灰色背景
}

• 目的分析：为了优化选中项的视觉反馈，让用户更容易识别当前选中的是哪一项，需要为选中项设置特定的背景色。
• 解决步骤：使用QSS（Qt Style Sheets）样式表，通过选择器#pageMusicList::item:selected选中pageMusicList中被选中的列表项，将其背景色设置为浅灰色（#EFEFEF）。

e. 垂直滚动条美化

QScrollBar:vertical {border: none; // 无边框width: 10px; // 宽度background-color: #FFFFFF; // 背景/* 可继续添加更多样式设置，如句柄样式等 */
}

• 目的分析：默认的垂直滚动条样式可能与整个界面的风格不一致，为了使滚动条与界面风格相匹配，需要对其进行美化。
• 解决步骤：使用QSS样式表，通过选择器QScrollBar:vertical选中垂直滚动条，设置其无边框、宽度为10px、背景色为白色。还可以根据需要继续添加更多的样式设置，如句柄的样式等。

五、总结与扩展

1. 模块价值

• 解耦设计：
  • MusicList和Music类将数据管理和界面显示进行了分离，就像搭积木一样，不同的功能模块相互独立。
  • 当需要修改数据管理部分时，不会对界面显示产生影响；反之，修改界面显示也不会影响数据管理。这使得代码的维护和扩展变得更加容易。
• 类型安全：
  • 枚举PageType明确地定义了不同的页面类型，就像给每个页面贴上了清晰的标签。
  • 避免了使用一些含义不明确的数字或字符串来表示页面类型，提高了代码的可读性和可维护性。
• 用户体验：
  • 自定义控件ListItemBox为用户提供了直观的交互反馈，当点击收藏按钮时，图标会立即切换。
  • 结合信号槽机制，能够实时更新界面，让用户在操作过程中感受到流畅的体验。

2. 常见问题与解决方案

问题	原因	解决方案
重复加载同一歌曲	没有记录已经加载过的文件路径，导致每次都可能重复添加同一首歌	使用QSet来记录已经加载过的文件路径，在添加新歌曲时先检查一下，如果已经存在就跳过
元数据解析失败	有些音乐文件可能没有元数据，或者文件格式不支持，导致无法读取歌曲名、歌手等信息	给这些情况设置默认值，比如“歌曲未知”“歌手未知”，同时筛选出支持的音频格式，只处理这些格式的文件
界面更新不同步	当音乐的收藏状态或者播放状态发生变化时，没有及时刷新相关的页面，导致显示的信息和实际情况不一致	当收藏或者播放状态变化时，强制刷新所有相关的页面，让界面显示最新的信息

3. 扩展方向

• 网络模块：目前的功能只能加载本地的音乐，后续可以添加网络模块，让软件能够从服务器上下载在线音乐，并且获取这些音乐的元数据和歌词，丰富音乐资源。
• 搜索功能：当前软件没有搜索功能，用户如果想听某首特定的歌曲，需要在大量的音乐列表中手动查找，非常不方便。可以添加一个搜索框，用户可以根据歌曲名或者歌手名快速定位到想听的音乐。
• 批量操作：现在只能一首一首地对音乐进行收藏、删除等操作，效率较低。可以支持多选功能，让用户能够一次选中多首音乐，然后一起进行收藏、删除等操作，提高操作效率。

📣 结语

音乐管理模块是QQMusic项目的核心基础，通过合理的类设计和信号槽机制，实现了从文件加载到界面显示的完整流程。理解这部分内容，不仅能掌握Qt文件操作、自定义控件和数据库应用，还能体会分层架构在实际项目中的应用。后续可结合播放控制模块，实现更丰富的音乐播放功能。

技术的魅力在于将复杂需求拆解为可实现的模块，每个细节的打磨都是进步的阶梯。坚持理解每一行代码的作用，终将积累出解决复杂问题的能力。