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 级别待补
Qt5.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 长出一个新对象,两者通过命名后缀区分,谁也不覆盖谁。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐