Qt进阶开发：QFileSystemModel的使用

一、QFileSystemModel的基本介绍

  QFileSystemModel 是 Qt 框架中用于管理和显示本地文件系统的 MVC 结构中的 Model。它可以与 QTreeView、QListView 或 QTableView 结合使用，实现文件管理功能。相比 QDirModel，QFileSystemModel 只会加载需要的目录，支持懒加载，在处理大文件夹时更高效。

主要特点：

• 继承自 QAbstractItemModel，提供标准的文件系统数据模型。
• 懒加载（Lazy Loading）：不会一次性加载整个文件系统，只会加载需要的部分，提升性能。
• 支持文件过滤（setFilter()、setNameFilters()）。
• 自动监听文件系统变化，实时更新 UI。

二、QFileSystemModel的基本使用

2.1 在 QTreeView 中使用

#include <QApplication>
#include <QTreeView>
#include <QFileSystemModel>int main(int argc, char *argv[]) {QApplication app(argc, argv);QFileSystemModel model;model.setRootPath(QDir::homePath());  // 设置根目录QTreeView treeView;treeView.setModel(&model);treeView.setRootIndex(model.index(QDir::homePath())); // 绑定视图treeView.show();return app.exec();
}

2.2 在 QListView 中使用

QListView listView;
listView.setModel(&model);
listView.setRootIndex(model.index(QDir::homePath()));
listView.show();

2.3 在 QTableView 中使用

QTableView tableView;
tableView.setModel(&model);
tableView.setRootIndex(model.index(QDir::homePath()));
tableView.show();

三、QFileSystemModel的常用API

3.1 设置根目录

model.setRootPath(QDir::homePath());  // 设置为用户目录

注意：setRootPath() 只是设置数据模型的根目录，并不会影响 QTreeView 显示的目录。要限制 QTreeView 的显示范围，需使用 setRootIndex()。

3.2 过滤文件

3.2.1 仅显示文件

model.setFilter(QDir::Files | QDir::NoDotAndDotDot);

QDir::Files 只显示文件，QDir::NoDotAndDotDot 过滤掉 . 和 … 目录。

3.2.2 只显示特定后缀的文件

model.setNameFilters(QStringList() << "*.cpp" << "*.h");
model.setNameFilterDisables(false); // 过滤掉不符合的文件

这将只显示 .cpp 和 .h 文件。

3.2.3 只显示目录

model.setFilter(QDir::Dirs | QDir::NoDotAndDotDot);

只显示目录，隐藏所有文件。

四、监听文件系统变化

1. QFileSystemModel常见信号

2. 信号的使用示例

2.1 监听目录加载完成

当 QFileSystemModel 完成某个目录的加载时，可以使用 directoryLoaded() 信号：

#include <QApplication>
#include <QTreeView>
#include <QFileSystemModel>
#include <QDebug>int main(int argc, char *argv[]) {QApplication app(argc, argv);QFileSystemModel model;QObject::connect(&model, &QFileSystemModel::directoryLoaded, [](const QString &path) {qDebug() << "目录加载完成：" << path;});model.setRootPath(QDir::homePath());QTreeView treeView;treeView.setModel(&model);treeView.setRootIndex(model.index(QDir::homePath()));treeView.show();return app.exec();
}

解释：

• 当某个目录的内容加载完成时，会输出 “目录加载完成：/home/user”（Linux/macOS）或 “目录加载完成：C:/Users/xxx”（Windows）。
• 适用场景：可以在目录加载完成后执行额外的操作，比如统计文件数量、更新 UI 状态等。

2.2 监听文件重命名

如果用户在文件管理器中修改了文件名，可以捕获 fileRenamed() 信号：

QObject::connect(&model, &QFileSystemModel::fileRenamed, [](const QString &path, const QString &oldName, const QString &newName) {qDebug() << "文件重命名：" << path + "/" + oldName << " -> " << newName;});

解释：

• fileRenamed(path, oldName, newName) 提供了文件所在目录、旧文件名和新文件名。
• 适用场景：可以记录日志、同步到数据库或通知 UI 更新。

2.3 监听根路径变化

当 setRootPath() 发生变化时，触发 rootPathChanged()：

QObject::connect(&model, &QFileSystemModel::rootPathChanged, [](const QString &newPath) {qDebug() << "根目录更改为：" << newPath;});

适用场景：当用户更改文件浏览的根目录时，可以执行特定操作，比如清除旧数据、更新 UI 等。

2.4 监听文件/目录添加

当新文件或目录被创建时，会触发 rowsInserted() 信号：

QObject::connect(&model, &QFileSystemModel::rowsInserted, [&model](const QModelIndex &parent, int start, int end) {for (int row = start; row <= end; ++row) {QModelIndex index = model.index(row, 0, parent);qDebug() << "新文件/文件夹：" << model.filePath(index);}});

解释：

• rowsInserted() 触发时，会输出新文件或目录的路径。
• 适用场景：当用户创建新文件/文件夹时，自动执行相应的 UI 更新或日志记录。

2.5 监听文件/目录删除

当某个文件或文件夹被删除时，会触发 rowsRemoved() 信号：

QObject::connect(&model, &QFileSystemModel::rowsRemoved, [](const QModelIndex &parent, int start, int end) {qDebug() << "文件/文件夹删除：" << start << "到" << end;});

3. 动态更新QLabel显示选中文件

#include <QApplication>
#include <QTreeView>
#include <QFileSystemModel>
#include <QLabel>
#include <QVBoxLayout>
#include <QWidget>
#include <QItemSelectionModel>int main(int argc, char *argv[]) {QApplication app(argc, argv);QFileSystemModel model;model.setRootPath(QDir::homePath());QTreeView treeView;treeView.setModel(&model);treeView.setRootIndex(model.index(QDir::homePath()));QLabel label;label.setText("选中文件路径显示区域");// 监听选中项变化QObject::connect(treeView.selectionModel(), &QItemSelectionModel::selectionChanged, [&model, &treeView, &label](const QItemSelection &selected, const QItemSelection &) {if (!selected.indexes().isEmpty()) {QModelIndex index = selected.indexes().first();label.setText(model.filePath(index));}});// 设置 UI 布局QWidget window;QVBoxLayout layout;layout.addWidget(&treeView);layout.addWidget(&label);window.setLayout(&layout);window.show();return app.exec();
}

输出显示：

4.右键菜单的实现

可以为 QTreeView 添加右键菜单，实现文件操作（打开、删除等）。

#include <QMenu>
#include <QAction>
#include <QDesktopServices>
#include <QUrl>void onContextMenu(const QPoint &pos) {QModelIndex index = treeView.indexAt(pos);if (!index.isValid()) return;QMenu menu;QAction *openAction = new QAction("打开", &menu);QAction *deleteAction = new QAction("删除", &menu);connect(openAction, &QAction::triggered, [index, &model]() {QString path = model.filePath(index);QDesktopServices::openUrl(QUrl::fromLocalFile(path));});connect(deleteAction, &QAction::triggered, [index, &model]() {model.remove(index);});menu.addAction(openAction);menu.addAction(deleteAction);menu.exec(treeView.viewport()->mapToGlobal(pos));
}

五、继承QFileSystemModel并进行自定义

继承 QFileSystemModel 并进行自定义，可以用来修改文件显示方式、拦截用户操作、隐藏某些文件或添加额外的功能。
可以通过继承 QFileSystemModel来：

• 自定义文件名显示（如：在文件名前加上 [文件] 或 [目录]）。
• 自定义文件图标。
• 隐藏某些文件/目录。
• 拦截文件删除或重命名操作。

示例 1：重写 data() 修改文件显示
默认情况下，QFileSystemModel 只显示文件名。如果我们想要修改显示内容（如：文件名前加上类型信息），可以重写 data() 方法：

#include <QFileSystemModel>
#include <QDebug>class CustomFileSystemModel : public QFileSystemModel {
public:explicit CustomFileSystemModel(QObject *parent = nullptr) : QFileSystemModel(parent) {}QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override {if (!index.isValid()) return QVariant();if (role == Qt::DisplayRole) {  // 修改显示文本QString fileName = QFileSystemModel::data(index, Qt::DisplayRole).toString();if (isDir(index))return "[目录] " + fileName;elsereturn "[文件] " + fileName;}return QFileSystemModel::data(index, role);}
};

示例 2：自定义文件图标
如果想要为特定类型的文件设置不同的图标（如 .txt 用文本图标，.cpp 用代码图标），可以重写 data() 的 Qt::DecorationRole：

#include <QFileIconProvider>
#include <QFileInfo>class CustomFileSystemModel : public QFileSystemModel {
public:explicit CustomFileSystemModel(QObject *parent = nullptr) : QFileSystemModel(parent) {}QVariant data(const QModelIndex &index, int role = Qt::DecorationRole) const override {if (!index.isValid()) return QVariant();if (role == Qt::DecorationRole) {QFileInfo fileInfo = this->fileInfo(index);if (fileInfo.suffix() == "txt")return QIcon(":/icons/text.png"); // 替换为你的图标else if (fileInfo.suffix() == "cpp" || fileInfo.suffix() == "h")return QIcon(":/icons/code.png"); // 替换为你的图标else if (fileInfo.isDir())return QIcon(":/icons/folder.png"); // 替换为你的文件夹图标}return QFileSystemModel::data(index, role);}
};

示例 2：自定义双击打开文件
如果希望在双击文件时执行特定操作（如：打开文件或显示信息），可以在 QTreeView 中监听 doubleClicked() 信号：

QObject::connect(&treeView, &QTreeView::doubleClicked, [&](const QModelIndex &index) {QString filePath = model.filePath(index);if (model.isDir(index)) {qDebug() << "双击打开目录：" << filePath;} else {qDebug() << "双击打开文件：" << filePath;QDesktopServices::openUrl(QUrl::fromLocalFile(filePath));}
});

下面是一个完整的示例，将以上功能整合到 QTreeView 中：

#include <QApplication>
#include <QTreeView>
#include <QFileSystemModel>
#include <QVBoxLayout>
#include <QWidget>
#include <QMessageBox>
#include <QDesktopServices>
#include <QUrl>class CustomFileSystemModel : public QFileSystemModel {
public:explicit CustomFileSystemModel(QObject *parent = nullptr) : QFileSystemModel(parent) {}QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override {if (!index.isValid()) return QVariant();if (role == Qt::DisplayRole) {QString fileName = QFileSystemModel::data(index, Qt::DisplayRole).toString();return isDir(index) ? "[目录] " + fileName : "[文件] " + fileName;}return QFileSystemModel::data(index, role);}
};int main(int argc, char *argv[]) {QApplication app(argc, argv);CustomFileSystemModel model;model.setRootPath(QDir::homePath());QTreeView treeView;treeView.setModel(&model);treeView.setRootIndex(model.index(QDir::homePath()));QObject::connect(&treeView, &QTreeView::doubleClicked, [&](const QModelIndex &index) {QString filePath = model.filePath(index);QDesktopServices::openUrl(QUrl::fromLocalFile(filePath));});treeView.resize(800, 600);treeView.show();return app.exec();
}