QFileSystemWatcher Class
QFileSystemWatcher 类提供了一个用于监视文件和目录是否发生更改的接口。更多内容...
| 头文件： | #include <QFileSystemWatcher> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
| 继承自： | QObject |
- 所有成员列表（包括继承的成员）
- QFileSystemWatcher 属于“输入/输出与网络”模块。
注意：该类中的所有函数均为可重入的。
公共函数
| QFileSystemWatcher(QObject *parent = nullptr) | |
| QFileSystemWatcher(const QStringList &paths, QObject *parent = nullptr) | |
| virtual | ~QFileSystemWatcher() |
| bool | addPath(const QString &path) |
| QStringList | addPaths(const QStringList &paths) |
| QStringList | directories() const |
| QStringList | files() const |
| bool | removePath(const QString &path) |
| QStringList | removePaths(const QStringList &paths) |
信号
| void | directoryChanged(const QString &path) |
| void | fileChanged(const QString &path) |
详细说明
QFileSystemWatcher 通过监视指定路径列表，来监视文件系统中文件和目录的变化。
调用addPath()来监视特定的文件或目录。可以使用addPaths()函数添加多个路径。可以使用removePath()和removePaths()函数删除现有路径。
QFileSystemWatcher 会检查添加到其中的每个路径。通过files() 函数可访问已添加到 QFileSystemWatcher 中的文件，通过directories() 函数可访问目录。
当文件被修改、重命名或从磁盘删除时，会触发fileChanged() 信号。同样地，当目录或其内容被修改或删除时，会触发directoryChanged() 信号。请注意，一旦文件被重命名或从磁盘删除，QFileSystemWatcher 就会停止对其的监视；一旦目录被从磁盘删除，也会停止对其的监视。
- 注：
- 在运行不支持 inotify 的 Linux 内核的系统上，包含被监视路径的文件系统无法卸载。
- 监控文件和目录的修改会消耗系统资源。这意味着您的进程同时能够监控的文件和目录数量是有限的。 例如，在所有 BSD 变体中，每个被监视的文件都需要一个打开的文件描述符。某些系统默认将打开的文件描述符数量限制为 256 个。这意味着，如果您的进程尝试向文件系统监视器中添加超过 256 个文件或目录，则addPath() 和addPaths() 将会失败。 另请注意，除了用于监控文件的文件描述符外，您的进程可能还打开了其他文件描述符，这些其他打开的描述符也会计入总数。macOS 使用不同的后端，因此不会遇到此问题。
成员函数文档
QFileSystemWatcher::QFileSystemWatcher(QObject *parent = nullptr)
使用给定的parent 创建一个新的文件系统监视器对象。
QFileSystemWatcher::QFileSystemWatcher(const QStringList &paths, QObject *parent = nullptr)
使用给定的parent 创建一个新的文件系统监视器对象，该对象用于监视指定的paths 列表。
[virtual noexcept] QFileSystemWatcher::~QFileSystemWatcher()
销毁文件系统监视器。
bool QFileSystemWatcher::addPath(const QString &path)
如果path 存在，则将path 添加到文件系统监视器中。如果不存在该路径，或者该路径已被文件系统监视器监视，则不会添加该路径。
如果path 指定的是一个目录，则当path 被修改或从磁盘删除时，将发出directoryChanged() 信号；否则，当path 被修改、重命名或删除时，将发出fileChanged() 信号。
如果监视成功，则返回 true。
监视失败的原因通常取决于系统，但可能包括资源不存在、访问失败，或者平台设有监视总数限制时达到该限制。
注意： 同时可监视的文件和目录数量可能存在 系统相关的限制。如果达到此限制，则不会监视path ，并返回 false。
另请参阅 addPaths() 和removePath()。
QStringList QFileSystemWatcher::addPaths(const QStringList &paths)
将paths 中的每个路径添加到文件系统监视器中。如果路径不存在，或者已被文件系统监视器监视，则不会添加这些路径。
如果路径指定的是一个目录，则当该路径被修改或从磁盘删除时，将触发directoryChanged()信号；否则，当路径被修改、重命名或删除时，将触发fileChanged()信号。
返回值是一个包含无法被监视的路径的列表。
监视失败的原因通常取决于系统，但可能包括资源不存在、访问失败，或者平台设有监视总数限制（如果平台有此限制）。
注意： 同时可监视的文件和目录数量可能受 系统限制。 如果已达到此限制，超出部分的paths 将不会被监视，并将被添加到返回的QStringList 中。
另请参阅 addPath() 和removePaths()。
QStringList QFileSystemWatcher::directories() const
返回一个包含正在监视的目录路径的列表。
另请参阅 files()。
[private signal] void QFileSystemWatcher::directoryChanged(const QString &path)
当指定path 下的目录被修改（例如，文件被添加或删除）或从磁盘中删除时，会发出此信号。请注意，如果在短时间内发生多次更改，其中某些更改可能不会发出此信号。但是，更改序列中的最后一次更改总会触发此信号。
注意：这是一个 私有信号。它可以在信号连接中使用，但用户无法主动发出该信号。
另请参阅 fileChanged()。
[private signal] void QFileSystemWatcher::fileChanged(const QString &path)
当位于指定path 的文件被修改、重命名或从磁盘中删除时，会触发此信号。
注意：作为 一项安全措施，许多应用程序在保存已打开的文件时，会先写入新文件，然后删除旧文件。在您的插槽函数中，您可以检查watcher.files().contains(path) 。如果返回false ，请检查该文件是否仍存在，然后调用addPath() 以继续监视该文件。
注意：这是一个 私有信号。它可以在信号连接中使用，但用户无法触发该信号。
另请参阅 directoryChanged()。
QStringList QFileSystemWatcher::files() const
返回一个包含正在监视的文件路径的列表。
另请参阅 directories()。
bool QFileSystemWatcher::removePath(const QString &path)
从文件系统监视器中移除指定的path 。
如果监视操作成功，则返回 true。
监视移除失败的原因通常取决于系统，但可能是由于路径已被删除等原因。
另请参阅 removePaths() 和addPath()。
QStringList QFileSystemWatcher::removePaths(const QStringList &paths)
从文件系统监视器中移除指定的paths 。
返回值是一个列表，其中包含未能成功取消监视的路径。
监视移除失败的原因通常取决于系统，但也可能是因为该路径已被删除等原因。
另请参阅 removePath() 和addPaths()。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
