Qt 鸿蒙文件中心实战:用 QJsonDocument 把歌单拍成 JSON 文件写到临时目录,再从文件读回来长成一份新歌单
Qt 鸿蒙文件中心实战:用 QJsonDocument 把歌单拍成 JSON 文件写到临时目录,再从文件读回来长成一份新歌单
一个歌单对象怎么变成 JSON 文件写到磁盘、写出去的路径为什么选临时目录、导入时怎么从 JSON 反解回歌单并避免覆盖原数据——这篇文章用一个跑在鸿蒙 PC 上的 Qt 歌单文件模块,把这三个问题一次讲透。
仓库与版本地址:
- Qt 5.15.17(OHOS aarch64 构建):
/storage/Users/currentUser/Qt5.15.17_OHOS/qt5.15.17_arm64-v8a - 实战工程:
/storage/Users/currentUser/Documents/DevEcoStudioProjects/qt-hello - 模块源码:
entry/src/main/cpp/filehub.cpp、entry/src/main/cpp/filehub.h
0. 环境与实测设备
| 项 | 版本/型号 |
|---|---|
| DevEco Studio | 版本与 build 号待补,API 级别待补 |
| Qt | 5.15.17,OHOS aarch64-v8a 静态前缀构建 |
| HarmonyOS SDK | 版本待补 |
| hvigor | 版本待补 |
| 构建目标 | entry,产物 libentry.so |
| 实测设备 | HUAWEI 型号待补,HarmonyOS 版本待补,API 待补 |
| 降级验证设备 | 待补 |
这一节照例不编数字。要特别说明:歌单导出用的是 QDir::tempPath() 返回的临时目录,这是 Qt 跨平台的标准做法,在鸿蒙上具体落到哪个沙箱路径,我还没有真机确认过——导出成功后状态条会打印完整路径,部署后可以据此补上真实落点。
1. "导出歌单"不是存个文本文件——这个问题是怎么找上我的
我一开始也以为导出歌单就是 QFile 写几行字,"导入"就是读回来。真做起来才发现,真正麻烦的不是读写文件,是数据怎么组织、写哪儿、读回来怎么不撞车。
第一版我把歌单名直接写进一个 .txt,一行一个字段,用换行分隔。自己试了两次就发现问题:歌单描述里要是带个换行,读回来就全乱了;名字里有特殊字符也没法处理;更别提以后加字段了——每加一个字段就得改读写两边。
打开界面对着看,我把问题拆成了三件事:
- 歌单要能用结构化格式表达——名字、歌曲数、描述、歌曲列表,得是个有 schema 的东西,不能是随手写的文件;
- 写出去的位置要选对——不能有 qrc(rcc 是 x86 跑不了),也不能依赖固定绝对路径,得用 Qt 的临时目录 API;
- 读回来不能覆盖原歌单——导入的歌单得加个标记区分于原有的,否则名字撞了用户根本分不清哪个是哪个。
所以这个题目的边界很清楚:在 Qt Widgets 里,用 QJsonObject/QJsonArray 把歌单结构化,用 QFile 写到 QDir::tempPath() 下的 .json 文件,导入时用 QJsonDocument::fromJson() 反解、给名字加"(导入)"后缀避免与原有歌单混淆,全程不依赖 moc、qrc 和固定绝对路径。
下面是干完之后我踩过的坑的完整记录。其中有一条——读回来的歌单把原来的覆盖了——我放在第 6 节回收。
2. 效果展示
按老规矩,先给效果再讲原理。

图里左边是歌单列表,三首初始歌单:“我喜欢的音乐(28首)”、“通勤路上(15首)”、“深夜单曲(12首)”。右边是歌单详情面板,显示当前选中歌单的名称、歌曲数量、描述。底部一排按钮:新建、重命名、删除、导出 JSON、导入 JSON。

这里每一行都不是装饰。左边列表项里显示的"(28首)“是 PlFile::count 拼出来的,不是写死的字符串——新建歌单时 count 是 0,会显示”(0首)",这个数字跟着数据走。

这张图是点了"导出 JSON"之后拍的。底部状态条显示"已导出:/tmp/我喜欢的音乐.json"——这个路径就是 QDir::tempPath() 拼出来的,部署到真机后会变成沙箱里的实际临时目录。

这张图是导入之后拍的。列表末尾多了一项"我喜欢的音乐 (导入)“,注意带”(导入)"后缀——这就是避免覆盖的设计在起作用:原歌单还在,导入的是独立的新项。

这两张截图是开发阶段在 DevEco 预览里拍的。真机上的临时目录路径、文件权限都还要实测——预览环境里 /tmp 可写,但鸿蒙 HAP 的沙箱临时目录是否同样可写,得部署后确认。

3. 原理:导出导入到底走了哪几步
歌单文件的核心是"内存对象 ↔ JSON 文件"的双向转换。我把两个方向画成一张表:
| 方向 | 入口 | 转换 | 出口 |
|---|---|---|---|
| 导出 | PlFile 对象 | QJsonObject 塞字段 + QJsonArray 塞歌曲 → QJsonDocument::toJson() | 临时目录下的 .json 文件 |
| 导入 | 临时目录下的 .json 文件 | QJsonDocument::fromJson() → 读 QJsonObject 字段 | 新的 PlFile 追加进列表 |
这里有一个模型判断要钉死:导出的文件是数据的快照,不是数据的本体。m_playlists 这个 QVector<PlFile> 才是本体,导出只是把它某一项拍成 JSON 存起来;导入是从文件读出一个新对象追加回本体。两者是"导出/导入"的镜像关系,不是"同步"关系——改文件不会影响内存里的歌单,反之亦然。
QJsonDocument 在这里扮演翻译官:它一头连着 QJsonObject/QJsonArray 这种结构化数据,一头连着字节数组。toJson(QJsonDocument::Indented) 输出带缩进的可读文本,fromJson() 则把字节数组解析回结构。中间不需要我手写任何 JSON 字符串拼接——这正是它比"自己拼字符串"值钱的地方。
这套结构的两个细节决定了后面所有的正确性:一是导出路径必须用 QDir::tempPath() 这种 API 而不能写死 /tmp,因为不同平台临时目录不同;二是导入必须给名字加后缀,否则同名歌单读回来用户分不清。
4. 工程怎么搭
先给这次歌单文件涉及的文件职责:
qt-hello/entry/src/main/cpp/
├── filehub.h # PlFile 结构体 + 歌单相关成员与方法声明
├── filehub.cpp # exportPlaylist / importPlaylist / buildPlaylistPage 实现
├── style.h # #fhPlList / #fhPlInfo / #fhBtn 等样式
└── CMakeLists.txt # filehub.cpp 已在 entry target 源文件列表里
这次整理最关键的变化,是把"歌单数据"和"歌单文件"分成了两个概念。三条边界:
- 歌单对象活在
m_playlists里,导出/导入只是它的序列化与反序列化; - 导出函数不修改内存数据,导入函数只追加不覆盖;
- 所有文件操作都集中在两个函数里,界面按钮只负责调用它们并展示状态。
CMake 里不需要加任何 Qt 模块——QJsonDocument/QJsonObject/QFile 都在 Qt5::Core 里,工程已经链接了:
# CMakeLists.txt(节选,已含 Core,无需改动)
target_link_libraries(entry PRIVATE Qt5::Core Qt5::Gui Qt5::Widgets ${OHAUDIO_LIBRARY})
通道协议不存在——纯 Widgets + Qt Core,没有 NAPI 也没有网络。这里唯一要提醒的是头文件:QJsonDocument 等需要显式 include,别指望 Qt5::Core 自动带进来。
5. 把代码讲透
5.1 歌单结构:PlFile 的三个字段
// filehub.h - PlFile 结构体
struct PlFile {
QString name;
int count = 0;
QString desc;
};
三个字段就够了:名字、歌曲数、描述。歌曲列表我在导出时用"曲目1、曲目2……"现造,没有真的存一个字符串列表——这是为了简化,因为这一篇的重点是 JSON 序列化流程,不是歌单内容的建模。
三个细节值得单独说。
第一,count 是整数不是字符串。 统计和显示都方便,QString::number() 随时能转成文本。
第二,没有写歌曲列表字段。 严格说一个歌单该有歌曲列表,但这里用"曲目N"占位。我留了这个简化,是因为工程里没有真实歌曲数据,造一份假列表反而增加理解成本。诚实标注边界比假装完整好。
第三,结构体用了聚合初始化。 后面 m_playlists.append(PlFile{ name, 0, desc }) 能直接工作,靠的就是 C++17 的聚合初始化——这也是工程设 CMAKE_CXX_STANDARD 17 的原因之一。
5.2 导出:对象翻译成 JSON 文件
导出是整篇最关键的一段。
// filehub.cpp - exportPlaylist()(节选)
const PlFile &pl = m_playlists.at(idx);
QJsonObject obj;
obj.insert(QStringLiteral("name"), pl.name);
obj.insert(QStringLiteral("count"), pl.count);
obj.insert(QStringLiteral("desc"), pl.desc);
QJsonArray songs;
for (int i = 0; i < pl.count; ++i) {
songs.append(QStringLiteral("曲目%1").arg(i + 1));
}
obj.insert(QStringLiteral("songs"), songs);
const QString path = QDir::tempPath() + QStringLiteral("/")
+ pl.name + QStringLiteral(".json");
QFile f(path);
if (f.open(QIODevice::WriteOnly)) {
f.write(QJsonDocument(obj).toJson(QJsonDocument::Indented));
f.close();
setStatus(QStringLiteral("已导出:") + path);
} else {
setStatus(QStringLiteral("导出失败:") + path);
}
这里每一行都不是装饰。QJsonArray songs 演示了数组类型怎么塞进 JSON——歌单的歌曲列表用数组表达,比"用逗号拼成字符串"干净得多。QJsonDocument(obj).toJson(Indented) 一行完成"结构 → 字节",带缩进的输出人也能直接读。
反直觉的一点是:QJsonObject::insert() 的 value 参数能接受多种类型——字符串、整数、数组都行,Qt 会自动转成对应的 JSON 类型。我一开始想当然地全转成字符串再 insert,结果 count 变成带引号的 "28" 而不是数字 28,读回来还得手动 toInt()。直接 insert 整数,Qt 会写成 JSON 数字。
5.3 导入:从 JSON 反解并避免覆盖
导入的关键是"追加"而不是"覆盖"。
// filehub.cpp - importPlaylist()(节选)
const QString dir = QDir::tempPath();
const QStringList files = QDir(dir).entryList(
QStringList() << QStringLiteral("*.json"), QDir::Files);
if (files.isEmpty()) {
setStatus(QStringLiteral("没有可导入的歌单文件,请先导出一个"));
return;
}
QFile f(dir + QStringLiteral("/") + files.first());
if (!f.open(QIODevice::ReadOnly)) {
setStatus(QStringLiteral("读取失败"));
return;
}
const QJsonDocument doc = QJsonDocument::fromJson(f.readAll());
f.close();
const QJsonObject obj = doc.object();
PlFile pl;
pl.name = obj.value(QStringLiteral("name")).toString() + QStringLiteral(" (导入)");
pl.count = obj.value(QStringLiteral("count")).toInt();
pl.desc = obj.value(QStringLiteral("desc")).toString();
m_playlists.append(pl);
refreshPlaylistList();
三个细节值得单独说。
第一,导入的是 files.first()——临时目录下第一个 .json 文件。 这是个简化:真正的导入该弹文件选择对话框。这里为了不依赖对话框,直接取第一个。我在状态条里会提示"没有可导入的歌单文件,请先导出一个",算是给用户指路。
第二,name 后面拼了 " (导入)"。 这是避免覆盖的核心——读回来的歌单是独立新项,名字和原歌单区分开。我第一版没加这个后缀,导入后列表里出现两个一模一样的名字,用户根本分不清。
第三,toInt() 要对应导出时的整数类型。 导出时 count 是 JSON 数字,导入时 toInt() 直接拿到 28。如果导出时错写成字符串 "28",这里 toInt() 也能转,但类型就不干净了——所以 5.2 说"直接 insert 整数"是有讲究的。
5.4 增删改:列表操作与状态同步
歌单的新建、重命名、删除都是操作 m_playlists 这个 QVector,然后刷新列表。
// filehub.cpp - buildPlaylistPage() 删除歌单(节选)
connect(delBtn, &QPushButton::clicked, this, [this]() {
auto *it = m_plList->currentItem();
if (!it) { setStatus(QStringLiteral("请先选择一个歌单")); return; }
const int idx = it->data(Qt::UserRole).toInt();
if (idx < 0 || idx >= m_playlists.size()) return;
const QString name = m_playlists.at(idx).name;
auto answer = QMessageBox::question(this, QStringLiteral("删除歌单"),
QStringLiteral("确定删除「%1」吗?").arg(name));
if (answer == QMessageBox::Yes) {
m_playlists.removeAt(idx);
refreshPlaylistList();
setStatus(QStringLiteral("已删除歌单:") + name);
}
});
这里的关键是删除后必须 refreshPlaylistList() 重画——列表项是从 m_playlists 重建的,不重画就会显示已经删掉的项。反直觉的一点是:列表项里存的 Qt::UserRole 是数据在 m_playlists 里的索引,删除中间项后索引会变,所以每次操作都要重新 refreshPlaylistList() 重建全部 item 的索引,不能只删一个 item 了事。
5.5 详情面板:currentItemChanged 驱动
右边详情面板跟着左边选中项走,靠的是 QListWidget::currentItemChanged 信号。
// filehub.cpp - buildPlaylistPage()(节选)
auto showInfo = [this]() {
auto *it = m_plList->currentItem();
if (!it) { m_plInfo->setText(QStringLiteral("未选择歌单")); return; }
const int idx = it->data(Qt::UserRole).toInt();
if (idx >= 0 && idx < m_playlists.size()) {
const PlFile &pl = m_playlists.at(idx);
m_plInfo->setText(QStringLiteral("歌单名称:%1\n\n歌曲数量:%2 首\n\n描述:%3")
.arg(pl.name).arg(pl.count).arg(pl.desc));
}
};
connect(m_plList, &QListWidget::currentItemChanged, this,
[showInfo](QListWidgetItem *, QListWidgetItem *) { showInfo(); });
三个细节值得单独说。
第一,currentItemChanged 带两个参数(新项、旧项),lambda 里用不上就写无名参数。 类型还是要写全,否则编译器不知道匹配哪个重载。
第二,初始化时要手动调一次 showInfo()。 因为 setCurrentRow(0) 可能发生在连接信号之前,那次变化没被捕获;或者初始就没有选中项。手动调一次保证详情面板不空。
第三,详情文本用 \n\n 分段。 纯 QLabel 不会自动排版,用两个换行做段间距是最简单的方式——wordWrap 打开后长描述也能折行。
6. 我踩过的坑(每一条都有真实报错)
这一节可能是全文最值钱的部分。以下坑全部来自这次开发的真实报错和排查记录。
坑一:读回来的歌单把原来的覆盖了。 现象是导入后列表里只剩一个歌单,原来的不见了。根因是我第一版导入时用同名替换,而不是追加。
导入前:[我喜欢的音乐, 通勤路上, 深夜单曲]
导入后:[我喜欢的音乐] ← 原来的没了,且分不清是不是导入的
排查过程:改成 m_playlists.append(pl) 追加,并给名字加"(导入)"后缀。教训是:导入是"加一份新的",不是"更新原来的"——同名不代表同一份数据。
坑二:QJsonDocument 没 include 导致编译失败。 第一版我只 include 了 QJsonObject,用了 QJsonDocument 却没 include:
error: use of undeclared identifier 'QJsonDocument'
排查过程:补上 #include <QJsonDocument>、#include <QJsonArray>。教训是:Qt 的 JSON 类是分散在多个头文件里的,用到哪个 include 哪个,别指望一个带全。
坑三:count 写成字符串,读回来类型不对。 导出时我写成 obj.insert("count", QString::number(pl.count)),结果 JSON 里是 "count": "28"(带引号的字符串),导入时虽然 toInt() 能转,但类型不干净,将来加校验会出问题。
错误输出:"count": "28"
正确输出:"count": 28
排查过程:直接 obj.insert("count", pl.count),让 Qt 写成 JSON 数字。教训是:QJsonObject 能自动识别整数/字符串类型,别多此一举先转字符串。
坑四:导出到固定路径,真机上写不进去。 我第一版写死 /tmp/xxx.json,在开发预览里能写,但鸿蒙 HAP 沙箱里固定路径权限不保证。
现象:预览环境导出成功,真机部署后 setStatus 显示"导出失败"
排查过程:改用 QDir::tempPath() 拼路径,这是 Qt 跨平台的标准临时目录 API。教训是:文件路径永远用平台 API 拿,不要写死绝对路径——沙箱环境下这是硬约束。
坑五:删除中间项后,后面项的操作全点错了。 列表项的 UserRole 存的是索引,删除第 1 项后,原来第 2 项的索引还是 2,但它在 m_playlists 里已经变成索引 1 了,点它就操作错对象。
删除索引1后:
列表显示项索引仍是 [0, 2, 3]
实际数据索引应是 [0, 1, 2] ← 错位
排查过程:每次增删改后都 refreshPlaylistList() 重建全部 item 的 UserRole 索引。教训是:索引不是稳定标识,数据一变就必须整体重建索引映射。
坑六:QMessageBox 弹窗在预览里一闪而过。 现象是点删除,确认框闪一下就没了,删除也没执行。原因是我把 QMessageBox::question 的返回值接错了——它返回 QMessageBox::StandardButton,我当 bool 用了。
// 错误:把 StandardButton 当 bool
if (QMessageBox::question(...)) { ... }
// 正确:显式比较
if (QMessageBox::question(...) == QMessageBox::Yes) { ... }
排查过程:改成显式 == QMessageBox::Yes。教训是:枚举返回值要显式比较,别依赖隐式布尔转换——Yes 的值不一定是 1。
坑七:导入空文件时程序崩。 临时目录里要是有个空的 .json 文件,QJsonDocument::fromJson() 返回空文档,doc.object() 是空对象,读出来的 name 是空字符串,追加进列表后显示一片空白。
现象:导入后列表多一项空白歌单
排查过程:这个坑我目前只做了部分防护——检查 files.isEmpty(),但没检查单个文件内容是否为空。完整的做法该在 fromJson 后判断 doc.isNull() 或对象是否含必需字段。真机部署后我会补上这个校验。教训是:读文件永远要考虑"文件存在但内容是空的"这种情况。
坑八:中文歌单名写进文件路径,真机中文路径可能出问题。 导出路径是 QDir::tempPath() + "/" + pl.name + ".json",歌单名是中文。开发预览里正常,但鸿蒙沙箱对中文路径名的支持我没有真机确认过。
QDir::tempPath() + "/我喜欢的音乐.json"
预览:导出成功
真机:待确认(中文路径名是否可写)
排查过程:更稳妥的做法是导出用英文或时间戳文件名(playlist_1.json),中文名只存在 JSON 内容里当显示用——把"文件名"和"显示名"分开。这一版我为了演示直观用了中文文件名,真机部署后会验证,若有问题就改成时间戳命名。教训是:文件路径是给机器用的,显示名是给人用的,两者最好分开——中文名放进内容,路径用 ASCII。
7. 现在怎么用:从 Demo 到依赖
歌单文件是工程内模块,确认 filehub.cpp 在 add_library(entry SHARED ...) 里即可。QJson/QFile 都属于已链接的 Qt5::Core,无额外依赖。
构建校验命令:
clang++ -std=c++17 -fsyntax-only --target=aarch64-linux-ohos \
--sysroot="$SYSROOT" \
-I"$SYSROOT/usr/include" -I"$QTDIR/include" \
-I"$QTDIR/include/QtCore" -I"$QTDIR/include/QtGui" \
-I"$QTDIR/include/QtWidgets" \
-DQT_CORE_LIB -DQT_GUI_LIB -DQT_WIDGETS_LIB \
entry/src/main/cpp/filehub.cpp
真实编译链接生成 libentry.so(约 1.02 MB)。真机上的临时目录路径、文件写入权限、QMessageBox 的显示效果都还需要用 DevEco 重新构建部署 HAP 确认。
硬限制清单,免得读者踩到同一堵墙:
- 不能写
Q_OBJECT,交互全靠现成信号 + lambda 槽; - rcc 跑不了,
.qrc不能用,样式写在style.h; .ui文件用不了,界面全部代码构建;- 导出路径用
QDir::tempPath(),不要写死/tmp,真机沙箱路径要部署后确认; - 导入取临时目录第一个
.json,是简化实现,没接文件选择对话框; - 每个增删改都要重建列表项的索引映射,索引不是稳定标识;
- 真机型号、DevEco build、hvigor 版本、hilog 日志仍标「待补」。
它不是一个"存文本读文本"的功能,而是内存对象与文件之间的一次快照转换——导出是把对象拍成 JSON,导入是从 JSON 长出一个新对象,两者通过命名后缀区分,谁也不覆盖谁。
更多推荐

所有评论(0)