Qt 鸿蒙文件工具实战:用一个规则枚举加一个新旧名对照表把前缀后缀查找替换序号大小写做成可预览的批量改名,再用一对字符串的撤销栈让每一次执行都能一键还原
Qt 鸿蒙文件工具实战:用一个规则枚举加一个新旧名对照表把前缀后缀查找替换序号大小写做成可预览的批量改名,再用一对字符串的撤销栈让每一次执行都能一键还原
六种改名规则怎么用一个字符串分支统一调度、预览表为什么不能直接改原数据、撤销栈里为什么只存新旧名一对字符串就够——这篇文章用一个跑在鸿蒙 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/filetools.cpp、entry/src/main/cpp/filetools.h
0. 环境与实测设备
| 项 | 版本/型号 |
|---|---|
| DevEco Studio | 版本与 build 号待补,API 级别待补 |
| Qt | 5.15.17,OHOS aarch64-v8a 前缀构建 |
| HarmonyOS SDK | 版本待补 |
| hvigor | 版本待补 |
| 构建目标 | entry,产物 libentry.so |
| 实测设备 | HUAWEI 型号待补,HarmonyOS 版本待补,API 待补 |
| 降级验证设备 | 待补 |
这一节只列真实信息。改名规则 6 种、序号补零固定 3 位、演示文件 9 个、撤销栈元素是 QPair<QString, QString>——都是代码里的真实值。真机上的键盘弹出、批量重绘性能我还没有数据,标「待补」。
1. 批量改名不是"循环 setText"——这个问题是怎么找上我的
我一开始也以为批量重命名就是循环一遍文件、每个调用 setText 改个名。真做起来才发现,用户要的根本不是"改",而是"先看清楚再改,改错了能退回来"。
第一版我做的就是循环改名,点一下按钮全改完。自己试了一下就冒冷汗:六个文件一起改,改完发现前缀拼错了,我连"改之前叫什么"都找不回来了——原数据已经被覆盖。更要命的是,序号重命名这种规则,一旦执行就和原文件名彻底脱钩,想手动改回来都不知道对应关系。
对着界面想清楚,我把问题拆成三件事:
- 规则要能预览——设完规则先算出每个文件的新名字,摆在新旧对照表里给人看,这一步绝对不能动原数据;
- 原数据和预览数据要分开——
oldName是真相,newName是提案,只有点"执行"才把提案变成真相; - 执行要能撤销——记下每次改名的"旧 → 新"一对字符串,撤销就是把它们换回去,多步操作能一层层退。
所以这个题目的边界很清楚:在 Qt Widgets 里,用一个规则枚举字符串分支把六种改名算法统一调度,用 oldName/newName 双字段把"真相"和"提案"分开,用 QVector<QPair<QString,QString>> 做撤销栈,预览只填提案不碰真相,执行才提交并压栈,全程不依赖 moc、qrc 和真实文件系统写入。
下面是干完之后我踩过的坑的完整记录。其中有一条——勾选状态被刷新冲掉——我放在第 6 节回收。
2. 效果展示
按老规矩,先给效果再讲原理。

图里顶部一行是规则区:规则下拉(添加前缀/添加后缀/查找替换/序号重命名/转小写/转大写)、两个参数输入框、起始序号微调框,右边三个按钮"预览规则"“执行重命名”“撤销”。中间上下两个表:上面是可选文件表(原文件名 + 选中勾选列),下面是新旧名预览表(原文件名、新文件名、状态)。

这里每一行都不是装饰。文件表的勾选列是真正的 QTableWidgetItem 复选,用户可以勾掉不想改的文件;预览表的"状态"列区分"将改名"和"无变化"——后者是新旧名相同的情况,提示用户这个规则对它无效。

这张图是我选了"序号重命名"、前缀填 IMG_、起始 1 之后拍的。预览表里 IMG_0001.jpg → IMG_001.jpg、IMG_0002.jpg → IMG_002.jpg 一行行排开,序号补零 3 位,扩展名保留。

这两张截图是开发阶段在 DevEco 预览里拍的。真机上表格滚动、勾选框触摸区域可能有差别,但改名逻辑不受影响——因为所有计算都在数据模型里,表格只是显示 RenameEntry 数组。

3. 原理:一次改名走哪几步
批量重命名的核心是"提案 → 预览 → 提交 → 压栈"四段式。我把数据字段和它们的角色列成一张表:
| 字段 | 角色 | 什么时候被写 | 什么时候被读 |
|---|---|---|---|
oldName | 真相(当前文件名) | 初始化、执行提交、撤销 | 计算新名、显示原名列 |
newName | 提案(预览结果) | 应用规则时 | 显示新名列、执行提交 |
checked | 用户选择 | 勾选框变化 | 决定哪些文件参与规则 |
m_undoStack | 历史 | 执行提交时压栈 | 撤销时出栈 |
这里有一个模型判断值得单独说:oldName 是唯一的真相,newName 只是待提交的提案。 这个区分是整个页面安全的基石——预览阶段反复重算 newName,oldName 纹丝不动,所以用户怎么调规则都不会破坏原数据。只有点"执行"的那一刻,才把 newName 赋给 oldName,完成提交。
| 事件 | 方向 | 触发对象 | 应用要回答什么 |
|---|---|---|---|
| 点"预览规则" | UI → 逻辑 | QPushButton | 用当前规则算出所有勾选文件的新名,填预览表 |
| 勾选框变化 | UI → 逻辑 | QTableWidget | 哪个文件被勾选/取消,重算预览 |
| 点"执行重命名" | UI → 逻辑 | QPushButton | 把提案提交为真相,压入撤销栈 |
| 点"撤销" | UI → 逻辑 | QPushButton | 出栈,把一对字符串换回去 |
节末放一句:预览和提交是两件事,把它们分开,批量操作才敢下手。 第 5 节讲的规则引擎和撤销栈,都建立在这个分离之上。
4. 工程怎么搭
先给完整目录树:
entry/src/main/cpp/
├── main.cpp
├── musicplayerwindow.cpp # 主窗口,挂载所有页面
├── audioengine.cpp
├── filehub.cpp / .h # 第一批文件工具
├── filetools.cpp / .h # 本页所在模块
├── videoplayer.cpp / .h
├── style.h
└── CMakeLists.txt
这次整理最关键的变化,是把"改文件名"变成"可审计的改名事务"。我给模块定了三条边界:
- 规则计算只产出
newName,绝不碰oldName——这是提案与真相的分离; - 所有改名操作集中在
applyRule()/executeRename()/undoRename()三个函数,互不串味; - 撤销信息用最轻的
QPair<QString,QString>,不引入命令模式那套抽象——6 种规则、9 个文件,轻量就够。
三种操作的分工,代码骨架是这样的:
// filetools.cpp - BatchRenamePage 三个核心动作(节选)
void BatchRenamePage::applyRule(); // 只算 newName,填预览表
void BatchRenamePage::executeRename(); // newName → oldName,压栈
void BatchRenamePage::undoRename(); // 出栈,oldName 还原
收在两个容易忽略的细节。第一,checkCell() 构造的复选 item 要显式设置 flags 为 ItemIsUserCheckable | ItemIsEnabled | ItemIsSelectable,漏了 ItemIsEnabled 勾选框是灰的、点不动。第二,刷新文件表时要用 QSignalBlocker 挡住 itemChanged 信号——否则程序自己设置勾选状态也会触发回调,造成"刷新 → 触发 → 再刷新"的循环。
5. 把代码讲透
5.1 规则引擎:六个分支一个出口
六种改名规则我没有搞成六个类,而是一个 if/else if 链,每个分支产出 newName:
// filetools.cpp - BatchRenamePage::applyRule()(节选)
const QString old = e.oldName;
const int dot = old.lastIndexOf(QLatin1Char('.'));
const QString base = dot > 0 ? old.left(dot) : old;
const QString ext = dot > 0 ? old.mid(dot) : QString();
if (rule == QStringLiteral("添加前缀")) {
e.newName = a1 + old;
} else if (rule == QStringLiteral("添加后缀")) {
e.newName = base + a1 + ext; // 插在扩展名前面
} else if (rule == QStringLiteral("查找替换")) {
e.newName = old;
e.newName.replace(a1, a2);
} else if (rule == QStringLiteral("序号重命名")) {
const int num = m_start->value() + idx;
e.newName = a1 + QStringLiteral("%1").arg(num, 3, 10, QLatin1Char('0')) + ext;
} else if (rule == QStringLiteral("转小写")) {
e.newName = old.toLower();
} else if (rule == QStringLiteral("转大写")) {
e.newName = old.toUpper();
}
第一,扩展名要单独拆出来。 后缀、序号这两种规则必须把扩展名留在最后,否则 照片.jpg 加后缀会变成 照片_副本.jpg.bak 这种怪东西。用 lastIndexOf('.') 拆出 base 和 ext,是处理文件名的标准起手。
第二,序号补零用 arg(num, 3, 10, '0')。 宽度 3、进制 10、填充字符 '0',1 就变成 001。这样排序时 001, 002, ..., 010 才不会乱——不补零的话 10 会排在 2 前面。
第三,idx 只数勾选的文件。 取消勾选的文件不占用序号,所以 ++idx 放在每个处理分支的末尾、且只在勾选分支里执行。
反直觉陷阱:"添加后缀"和"添加前缀"用的不是同一个字符串。 前缀直接拼在整个 old 前面(a1 + old),后缀拼在 base 和 ext 之间(base + a1 + ext)。如果偷懒都写成 a1 + old,后缀规则就变成了另一个前缀规则。
5.2 预览表:提案的只读展示
预览阶段把 newName 填进表格,但绝不动 oldName:
// filetools.cpp - BatchRenamePage::refreshPreview()(节选)
for (const RenameEntry &e : m_entries) {
if (!e.checked || e.newName.isEmpty()) {
continue;
}
const int row = m_preview->rowCount();
m_preview->insertRow(row);
m_preview->setItem(row, 0, cell(e.oldName));
m_preview->setItem(row, 1, cell(e.newName));
m_preview->setItem(row, 2, cell(e.oldName == e.newName
? QStringLiteral("无变化") : QStringLiteral("将改名")));
}
第一,e.newName.isEmpty() 的条目被跳过。 取消勾选的文件、以及还没应用规则的文件,newName 是空的,不该出现在预览里。
第二,"无变化"状态是诚实提示。 转小写规则遇到本来就是小写的文件名,newName == oldName,标"无变化"而不是假装改了——用户看到这个会知道"这个规则对它无效",而不是以为执行了却没效果。
第三,预览表用 cell() 造不可编辑项。 预览是给人看的提案,不该被直接编辑;要改规则得回到上面的参数区重新预览。这避免了"改了预览表但规则没变"的不一致。
5.3 提交与撤销:一对字符串就够了
执行改名时,把提案变成真相,并把这一对存进撤销栈:
// filetools.cpp - BatchRenamePage::executeRename()(节选)
for (RenameEntry &e : m_entries) {
if (!e.checked || e.newName.isEmpty() || e.newName == e.oldName) {
continue;
}
m_undoStack.append(qMakePair(e.oldName, e.newName)); // 存旧→新
e.oldName = e.newName; // 提交
++count;
}
rebuildEntries(); // 清空所有 newName,回到"未预览"状态
撤销时出栈,按新名找回条目,把旧名还回去:
// filetools.cpp - BatchRenamePage::undoRename()(节选)
const QPair<QString, QString> last = m_undoStack.takeLast();
for (RenameEntry &e : m_entries) {
if (e.oldName == last.second) { // 用新名定位
e.oldName = last.first; // 还原旧名
break;
}
}
第一,撤销栈存的是"旧→新",弹出后按"新"定位、还原成"旧"。 一对字符串,不需要记录规则、参数、行号——因为撤销只关心"名字从什么变回什么",与怎么变的无关。
第二,rebuildEntries() 在提交后清空 newName。 提交完成后,预览表应该清空,否则用户会看到"已经改过的名字还列在预览里",误以为还没执行。
第三,撤销按 last.second(新名)匹配。 因为执行后条目的 oldName 已经变成了新名,要找的就是它。多步改名时,每次执行都压一对,撤销就一层层退——这是标准的栈语义。
反直觉陷阱:撤销的匹配用 oldName == last.second,不是用索引。 因为执行过程中可能有文件被取消勾选、顺序变化,用行号定位会错位。用名字内容定位虽然慢一点,但稳。
5.4 勾选与刷新的信号环
勾选框变化要同步到数据并重算预览,但程序刷新表格时也要设置勾选状态——这中间有个信号环:
// filetools.cpp - BatchRenamePage::refreshList()(节选)
QSignalBlocker blocker(m_fileList);
m_fileList->setRowCount(0);
m_fileList->setRowCount(m_entries.size());
for (int i = 0; i < m_entries.size(); ++i) {
m_fileList->setItem(i, 0, cell(m_entries.at(i).oldName));
m_fileList->setItem(i, 1, checkCell(m_entries.at(i).checked));
}
QSignalBlocker 挡住 itemChanged,程序自己设勾选时不触发回调。 否则 refreshList() 里 setItem 设置复选状态 → 触发 itemChanged → 回调里又调 refreshPreview() → 虽然不致命,但白白重算一遍,且如果用户正在交互会有闪烁。
三个细节:
- 用户手动点勾选框时,
itemChanged正常触发,回调里更新m_entries[row].checked并refreshPreview()——这才是真正需要响应的路径。 checkCell()设置ItemIsUserCheckableflags,是勾选框能点前提。- 回调里先判断
it->column() != 1就返回——只有勾选列的变化才关心,文件名列(不可编辑)的变化忽略。
5.5 参数校验:不是所有规则都要填参数
预览前我检查参数,但不是一刀切:
// filetools.cpp - BatchRenamePage::applyRule()(节选)
if ((rule == QStringLiteral("添加前缀") || rule == QStringLiteral("添加后缀")
|| rule == QStringLiteral("查找替换") || rule == QStringLiteral("序号重命名"))
&& a1.isEmpty()) {
setStatusText(m_status, QStringLiteral("该规则需要填写参数,请先输入"));
return;
}
转小写、转大写不需要任何参数,所以校验只覆盖那四个需要参数的规则。查找替换理论上 a2 可以为空(表示删除匹配内容),所以只校验 a1 查找内容非空。
降级说明:这套校验是"够用型"的——它不检查重名冲突(两个文件改成同一个名字)、不检查非法文件名字符。真要通用,执行前该做一次冲突检测,但演示场景里 9 个文件名各不相同,规则不会产生冲突,所以先不做。
6. 我踩过的坑(每一条都有真实报错)
这一节可能是全文最值钱的部分。以下坑全部来自这次开发的真实报错和排查记录。
坑一:勾选状态一刷新就丢。 第一版 refreshList() 没有 QSignalBlocker,程序设置复选 item 时触发 itemChanged,回调把 m_entries[row].checked 按 item 状态更新——看起来没问题,但执行改名后 refreshList() 重建表格,勾选状态在"重建 → 触发 → 更新 → 再重建"中乱套,用户勾掉的又回来了。修复就是用 QSignalBlocker 挡住程序自身的刷新信号。教训:表格自己刷新时,必须挡住它发出的变化信号,否则回调和刷新会互相打架。
坑二:后缀规则改出了 照片.jpg.bak 这种双扩展名。 原因是我一开始把"添加后缀"写成 a1 + old,和前缀共用了一行。真跑起来才发现后缀该插在扩展名前面。教训:前缀拼全名、后缀拆扩展名,这是两条不同的路径,不能图省事合并。
坑三:序号不补零,排序全乱。 第一版序号直接 QString::number(num),IMG_10.jpg 排在 IMG_2.jpg 前面——因为字符串排序里 '1' < '2'。改成 arg(num, 3, 10, '0') 补零到 3 位才正常。教训:凡是会参与排序的编号,一律补零到固定宽度。
坑四:撤销按行号定位,越撤越错。 我一开始撤销栈存的是行号,执行后如果有文件被取消勾选、列表重排,行号就指向了别的文件。改成存名字字符串、按 oldName == last.second 内容定位才稳。教训:撤销要记"内容"不要记"位置",位置会变、内容不会。
坑五:QLatin1Char('★') 渲染乱码。 这个坑在标签收藏页也踩了(见系列第 5 篇)。★ 码位 0x2605 超出 Latin1,必须用 QChar(0x2605)。教训:非 Latin1 字符一律 QChar(码位) 或 QStringLiteral。
坑六:执行改名后预览表没清空。 第一版提交后没调 rebuildEntries(),预览表还列着刚才的新名,用户以为没执行、又点一次,结果改了两次。教训:提交后必须把提案字段清空,让界面回到"未预览"的干净状态。
7. 现在怎么用:从 Demo 到依赖
接入方式和其他文件页一样,加源文件 + 挂载:
# entry/src/main/cpp/CMakeLists.txt(节选)
add_library(entry SHARED
main.cpp
musicplayerwindow.cpp
audioengine.cpp
filehub.cpp
filetools.cpp # ← 本页所在模块
videoplayer.cpp
)
// musicplayerwindow.cpp - buildContentPane()(节选)
m_pages->addWidget(new BatchRenamePage(this));
构建命令:
cd entry/.cxx/default/default/debug/arm64-v8a
cmake .
ninja
验证情况:鸿蒙 clang 15.0.4 全量 -fsyntax-only 退出码 0,DevEco cmake + ninja 增量重建退出码 0,libentry.so 已同步进 HAP 打包目录。真机上的输入与勾选体验还没测,标待补。
硬限制清单:
- 跑不了 moc,交互只能用现成信号 + lambda;
- 预览只填
newName,绝不碰oldName,这条边界不能破; - 勾选表刷新必须
QSignalBlocker挡信号; - 撤销栈存字符串不存行号;
- 序号补零固定 3 位,参与排序的编号都要补零;
- 演示数据内存模拟,执行改名不写真实磁盘,重启即失效。
它不是一个循环,而是把"看清提案"和"提交真相"拆成两步,再用一对字符串给每次提交留一条退路。如果这篇文章只能留一句话,我会留这句:批量操作让人安心的不是"改得快",而是"改之前能看清、改之后能退回"。
更多推荐




所有评论(0)