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 或目录。构造完成后，迭代器位于第一个目录条目之前。下面是按顺序遍历所有条目的方法：

QDirIteratorit("/etc"、 QDirIterator::Subdirectories);while(it.hasNext()) { QStringdir=it.next()；    qDebug() << dir;
   // /etc/. // /etc/.. // /etc/X11 // /etc/X11/fs // . . .}

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

QDirIteratorit("/sys"、 QStringList()<< "scaling_cur_freq"、 QDir::NoFilter、 QDirIterator::Subdirectories);while(it.hasNext()) { QFilef(it.next()); f.open(QIODevice::ReadOnly)；    qDebug() << f.fileName() << f.readAll().trimmed().toDouble() / 1000 << "MHz";
}

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

与 Qt 的容器迭代器不同，QDirIterator 是单向的（即不能以相反的顺序迭代目录），并且不允许随机访问。

注意： 该类已被弃用，可能会在 Qt 版本中删除。请使用QDirListing 代替。

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

成员类型文档

枚举 QDirIterator::IteratorFlag
flags QDirIterator::IteratorFlags

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

常量值说明
QDirIterator::NoIteratorFlags0x0默认值，表示无标志。迭代器将返回指定路径的条目。
QDirIterator::Subdirectories0x2同时列出所有子目录内的条目。
QDirIterator::FollowSymlinks0x1当与子目录结合使用时，该标志可以遍历指定路径的所有子目录，并跟随所有符号链接。符号链接循环（如 "link" => ". "或 "link" => ".."）会被自动检测并忽略。

IteratorFlags 类型是QFlags<IteratorFlag> 的类型定义。它存储 IteratorFlag 值的 OR 组合。

成员函数文档

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

构造一个 QDirIterator，它可以使用dir 的名称过滤器和正则过滤器遍历dir 的条目列表。您可以通过flags 传递选项，以决定目录的迭代方式。

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

dir 中的排序会被忽略。

注意： 要列出指向非现有文件的符号链接，必须将QDir::System 传递给标志。

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

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

构造一个可以遍历path 的 QDirIterator。可以通过flags 传递选项来决定如何遍历目录。

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

注意： 要列出指向非现有文件的符号链接，必须将QDir::System 传递给标志。

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

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

构造一个可以遍历path 的 QDirIterator，不带名称过滤，filters 用于条目过滤。您可以通过flags 传递选项，以决定目录的迭代方式。

默认情况下，filters 就是QDir::NoFilter ，flags 就是NoIteratorFlags ，这提供了与QDir::entryList() 相同的行为。

注意： 要列出指向非现有文件的符号链接，必须将QDir::System 传递给标志。

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

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

构造一个 QDirIterator，它可以使用nameFilters 和filters 遍历path 。您可以通过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() 以避免意外结果。

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

如果您对QFileInfo 感兴趣，请调用nextFileInfo() 而不是 next() 。

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

[since 6.3] QFileInfo QDirIterator::nextFileInfo()

将迭代器推进到下一个条目，并返回新条目文件信息。在使用此方法之前，应首先检查hasNext() 以避免意外结果。

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

当您只需要filePath() 时，请调用next() 而不是 nextFileInfo()。

此函数在 Qt 6.3 中引入。

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

QString QDirIterator::path() const

返回迭代器的基本目录。

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