Back to Qt.io
Contact Us Blog Download Qt
本页内容

QDirIterator Class

QDirIterator 类为目录条目列表提供了一个迭代器。更多内容...

头文件： #include <QDirIterator>
CMake： find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake： QT += core

公共类型

enum IteratorFlag { NoIteratorFlags, Subdirectories, FollowSymlinks }
flags IteratorFlags

公共函数

QDirIterator(const QDir &dir, QDirIterator::IteratorFlags flags = NoIteratorFlags)
QDirIterator(const QString &path, QDirIterator::IteratorFlags flags = NoIteratorFlags)
QDirIterator(const QString &path, QDir::Filters filters, QDirIterator::IteratorFlags flags = NoIteratorFlags)
QDirIterator(const QString &path, const QStringList &nameFilters, QDir::Filters filters = QDir::NoFilter, QDirIterator::IteratorFlags flags = NoIteratorFlags)
~QDirIterator()
QFileInfo fileInfo() const
QString fileName() const
QString filePath() const
bool hasNext() const
QString next()
(since 6.3) QFileInfo nextFileInfo()
QString path() const

详细说明

您可以使用 QDirIterator 逐个遍历目录中的条目。 它与QDir::entryList()和QDir::entryInfoList()类似，但由于它是一次列出一个条目，而不是一次性列出所有条目，因此可扩展性更好，更适合大型目录。它还支持递归列出目录内容，并支持跟随符号链接。与QDir::entryList()不同，QDirIterator不支持排序。

QDirIterator 的构造函数接受一个QDir 或一个目录作为参数。构造完成后，迭代器位于第一个目录条目前。以下是如何依次遍历所有条目的方法：

QDirIterator it("/etc",QDirIterator::Subdirectories);
while(it.hasNext()) {
    QString dir=it.next();
    qDebug() << dir;
   // /etc/.
    // /etc/..
    // /etc/X11
    // /etc/X11/fs
    // ...
}

以下是如何递归查找并读取所有按名称过滤的文件：

QDirIterator it("/sys",QStringList()<< "scaling_cur_freq",QDir::NoFilter,QDirIterator::子目录);
while(it.hasNext()) {
    QFile f(it.next());
    f.open(QIODevice::ReadOnly);
    qDebug() << f.fileName() << f.readAll().trimmed().toDouble() / 1000 << "MHz";
}

next QFileInfo () 和 () 函数会向前推进迭代器，并返回下一个目录条目的路径或 。您也可以直接调用 () 或 () 来获取当前文件路径，而无需先推进迭代器。 () 函数仅返回文件名，其工作原理与 () 类似。nextFileInfo QFileInfo filePath fileInfo fileName QDir::entryList

与 Qt 的容器迭代器不同，QDirIterator 是单向的（即无法按反向顺序遍历目录），且不支持随机访问。

注意：此类已 弃用，可能会在未来的 Qt 版本中被移除。请改用QDirListing ，参见《将 QDirIterator 移植到 QDirListing》。

另请参阅 QDir 和QDir::entryList()。

成员类型文档

enum QDirIterator::IteratorFlag
flags QDirIterator::IteratorFlags

此枚举描述了可用于组合配置QDirIterator 行为的标志。

常量值描述
QDirIterator::NoIteratorFlags0x0默认值，表示不指定任何标志。迭代器将返回指定路径下的条目。
QDirIterator::Subdirectories0x2同时列出所有子目录中的条目。
QDirIterator::FollowSymlinks0x1当与“子目录”标志结合使用时，此标志可启用遍历指定路径的所有子目录，并跟随所有符号链接。符号链接循环（例如，“link” => “.” 或 “link” => “..”）将被自动检测并忽略。

IteratorFlags 类型是QFlags<IteratorFlag> 的 typedef。它存储 IteratorFlag 值的或运算组合。

成员函数文档

QDirIterator::QDirIterator(const QDir &dir, QDirIterator::IteratorFlags flags = NoIteratorFlags)

构建一个 QDirIterator，该迭代器可遍历dir 的条目列表，并使用dir 中的名称过滤器和常规过滤器。您可以通过flags 传递选项，以决定目录的遍历方式。

默认情况下，flags 即为NoIteratorFlags ，其行为与QDir::entryList() 中的行为相同。

dir 中的排序将被忽略。

注意：若要 列出指向不存在文件的符号链接，必须将QDir::System 传递给 flags。

另请参阅 hasNext()、next() 和IteratorFlags 。

QDirIterator::QDirIterator(const QString &path, QDirIterator::IteratorFlags flags = NoIteratorFlags)

创建一个可遍历path 的 QDirIterator。您可以通过flags 传递选项，以确定目录的遍历方式。

默认情况下，flags 为NoIteratorFlags ，其行为与QDir::entryList() 中的行为相同。

注意：若要 列出指向不存在文件的符号链接，必须将QDir::System 传递给 flags。

另请参阅 hasNext()、next() 以及IteratorFlags 。

QDirIterator::QDirIterator(const QString &path, QDir::Filters filters, QDirIterator::IteratorFlags flags = NoIteratorFlags)

构建一个 QDirIterator，该迭代器可遍历path ，不进行名称过滤，并使用filters 作为条目过滤条件。您可以通过flags 传递选项，以决定目录的遍历方式。

默认情况下，filters 为QDir::NoFilter ，flags 为NoIteratorFlags ，其行为与QDir::entryList() 相同。

注意：若要 列出指向不存在文件的符号链接，必须将QDir::System 作为参数传递给 flags。

另请参阅 hasNext()、next() 和IteratorFlags 。

QDirIterator::QDirIterator(const QString &path, const QStringList &nameFilters, QDir::Filters filters = QDir::NoFilter, QDirIterator::IteratorFlags flags = NoIteratorFlags)

创建一个 QDirIterator，该迭代器可遍历path ，并使用nameFilters 和filters 。您可以通过flags 传递选项，以决定目录的遍历方式。

默认情况下，flags 为NoIteratorFlags ，其行为与QDir::entryList() 相同。

例如，可以使用以下迭代器遍历音频文件：

QDirIterator audioFileIt(audioPath, {"*.mp3", "*.wav"}, QDir::Files);

注意：若要 列出指向不存在文件的符号链接，必须将 `QDir::System ` 传递给标志参数。

另请参阅 hasNext()、next()、IteratorFlags 以及QDir::setNameFilters()。

[noexcept] QDirIterator::~QDirIterator()

销毁QDirIterator 。

QFileInfo QDirIterator::fileInfo() const

返回当前目录条目的QFileInfo 。

另请参阅 filePath() 和fileName()。

QString QDirIterator::fileName() const

返回当前目录条目的文件名，不包含前缀路径。

在遍历单个目录时，此函数非常方便。使用QDirIterator::Subdirectories 标志时，可使用filePath()获取完整路径。

另请参阅 filePath() 和fileInfo()。

QString QDirIterator::filePath() const

返回当前目录条目的完整文件路径。

另请参阅 fileInfo() 和fileName()。

bool QDirIterator::hasNext() const

如果目录中至少还有一个条目，则返回true ；否则，返回 false。

另请参见 next()、nextFileInfo()、fileName()、filePath() 和fileInfo()。

QString QDirIterator::next()

将迭代器向前移动到下一个条目，并返回该新条目的文件路径。如果hasNext()返回false ，则本函数不执行任何操作，并返回空的QString 。理想情况下，您应在调用此方法之前始终先调用hasNext()。

您可以调用fileName() 或filePath() 来获取当前条目的文件名或路径，或者调用fileInfo() 来获取当前条目的QFileInfo 。

如果您需要获取QFileInfo ，请调用nextFileInfo() 而不是 next()。

另请参阅 hasNext()、nextFileInfo()、fileName()、filePath() 以及fileInfo()。

[since 6.3] QFileInfo QDirIterator::nextFileInfo()

将迭代器向前移动到下一个条目，并返回该新条目的文件信息。如果hasNext()返回false ，则本函数不执行任何操作，并返回一个空的QFileInfo 。理想情况下，您应在调用此方法之前始终先调用hasNext()。

您可以调用fileName() 或filePath() 来获取当前条目的文件名或路径，或调用fileInfo() 来获取当前条目的QFileInfo 。

若仅需获取filePath()，请调用next() 而非 nextFileInfo()。

该函数在 Qt 6.3 中引入。

另请参阅 hasNext()、fileName()、filePath() 和fileInfo()。

QString QDirIterator::path() const

返回迭代器的根目录。

© 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.