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

QDirListing Class

QDirListing 类为目录条目提供了一个 STL 风格的迭代器。更多内容...

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

公共类型

class DirEntry
(since 6.8) class const_iterator
(since 6.8) class sentinel
enum class IteratorFlag { Default, ExcludeFiles, ExcludeDirs, ExcludeOther, ResolveSymlinks, …, FollowDirSymlinks }
flags IteratorFlags

公共函数

QDirListing(const QString &path, QDirListing::IteratorFlags flags = IteratorFlag::Default)
QDirListing(const QString &path, const QStringList &nameFilters, QDirListing::IteratorFlags flags = IteratorFlag::Default)
QDirListing(QDirListing &&other)
~QDirListing()
QDirListing::const_iterator begin() const
QDirListing::const_iterator cbegin() const
QDirListing::sentinel cend() const
QDirListing::sentinel end() const
QDirListing::IteratorFlags iteratorFlags() const
QString iteratorPath() const
QStringList nameFilters() const
QDirListing &operator=(QDirListing &&other)

详细说明

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

QDirListing 的构造函数接受一个目录路径字符串作为参数。以下是如何递归遍历所有条目的方法：

usingItFlag=QDirListing::IteratorFlag;
for(const auto &dirEntry: QDirListing(u"/etc"_s,ItFlag::Recursive)) {
    qDebug() << dirEntry.filePath();
   // /etc/.
    // /etc/..
    // /etc/X11
    // /etc/X11/fs
    // ...
}

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

使用F=QDirListing::IteratorFlag;
QDirListing dirList(u"/sys"_s,QStringList{u"scaling_cur_freq"_s},F::FilesOnly|F::Recursive);
for(const auto &dirEntry: dirList) {
    QFile f(dirEntry.filePath());
    if(f.open(QIODevice::ReadOnly))
        qDebug() << f.fileName() << f.readAll().trimmed().toDouble() / 1000 << "MHz";
}

以下是如何递归地仅列出普通文件的方法：

using F = QDirListing::IteratorFlag;
const auto flags = F::FilesOnly | F::Recursive;
for (const auto &dirEntry : QDirListing(u"/etc"_s, flags)) {
    // ...
}

以下是如何递归地仅列出普通文件和指向普通文件的符号链接的方法：

using F = QDirListing::IteratorFlag;
const auto flags = F::FilesOnly | F::Recursive | F::ResolveSymlinks;
for (const auto &dirEntry : QDirListing(u"/etc"_s, flags)) {
    // ...
}

QDirListing::const_iterator 该类实现了 C++20标准的 std::input_iterator 接口，即它是一个仅支持移动、仅支持向前、单遍遍历的迭代器，不允许随机访问。它可用于范围 for 循环（或与不要求随机访问迭代器的 C++20 范围算法配合使用）。 解引用一个有效的迭代器将返回一个QDirListing::DirEntry 对象。符号 (c)end() 标志着迭代的结束。解引用一个等于sentinel 的迭代器将导致未定义行为。

QDirListing::DirEntry 提供了QFileInfo API的子集（例如，fileName()、filePath()、exists()）。在内部，DirEntry 仅在需要时才构建QFileInfo 对象，即当相关信息尚未由其他系统函数获取时。您可以使用DirEntry::fileInfo()来获取QFileInfo 。例如：

using ItFlag = QDirListing::IteratorFlag;
for (const auto &dirEntry : QDirListing(u"/etc"_s, ItFlag::Recursive)) {
    // Faster
    if (dirEntry.fileName().endsWith(u".conf")) { /* ... */ }

    // This works, but might be potentially slower, since it has to construct a
    // QFileInfo, whereas (depending on the implementation) the fileName could
    // be known already
    if (dirEntry.fileInfo().fileName().endsWith(u".conf")) { /* ... */ }
}
using ItFlag = QDirListing::IteratorFlag;
for (const auto &dirEntry : QDirListing(u"/etc"_s, ItFlag::Recursive)) {
    // Both approaches are the same, because DirEntry will have to construct
    // a QFileInfo to get this info (for example, by calling system stat())

    if (dirEntry.size() >= 4'000 /* 4KB */) { /* ...*/ }
    if (dirEntry.fileInfo().size() >= 4'000 /* 4KB */) { /* ... */ }
}

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

成员类型文档

enum class QDirListing::IteratorFlag
flags QDirListing::IteratorFlags

该枚举类描述了可用于配置QDirListing 行为的标志。该枚举中的值可以进行位或运算。

常量值描述
QDirListing::IteratorFlag::Default0x000000列出所有条目，即文件、目录、符号链接（包括目标不存在的断开符号链接）以及特殊（其他）系统文件，详情请参阅 ExcludeOther。默认情况下，隐藏文件和目录以及特殊条目. 和.. 不会被列出。
QDirListing::IteratorFlag::ExcludeFiles0x000004不列出普通文件。当与 ResolveSymlinks 结合使用时，指向普通文件的符号链接也将被排除。
QDirListing::IteratorFlag::ExcludeDirs0x000008不列出目录。若与 ResolveSymlinks 结合使用，指向目录的符号链接也将被排除。
QDirListing::IteratorFlag::ExcludeOther0x000010[自 6.10 起] 不列出既非目录、普通文件也非符号链接的文件系统条目。
  • 在 Unix 系统中，特殊（其他）文件系统条目包括 FIFO、套接字、字符设备或块设备。更多详情请参阅 mknod 手册页。
  • 在 Windows 系统中（出于历史原因），.lnk 文件被视为特殊（其他）文件系统条目。
QDirListing::IteratorFlag::ResolveSymlinks0x000020根据符号链接目标的类型（而非符号链接本身）过滤符号链接。已断开的符号链接（即目标不存在的链接）将被排除，若要包含它们，请将 IncludeBrokenSymlinks 设为真。在不支持符号链接的操作系统上，此标志将被忽略。
QDirListing::IteratorFlag::IncludeBrokenSymlinks0x001000[自 6.11 起] 列出目标不存在的断开符号链接，无论 ResolveSymlinks 标志的状态如何。在不支持符号链接的操作系统上，此标志将被忽略。
QDirListing::IteratorFlag::FilesOnlyExcludeDirs | ExcludeOther仅列出普通文件。与 ResolveSymlinks 结合使用时，指向文件的符号链接也会被列出。
QDirListing::IteratorFlag::DirsOnlyExcludeFiles | ExcludeOther仅列出目录。若与 ResolveSymlinks 结合使用，指向目录的符号链接也将被列出。
QDirListing::IteratorFlag::IncludeHidden0x000040列出隐藏条目。若与 Recursive 结合使用，迭代过程还将递归进入隐藏子目录。
QDirListing::IteratorFlag::IncludeDotAndDotDot0x000080列出. 和.. 特殊条目。
QDirListing::IteratorFlag::CaseSensitive0x000100传递给 `QDirListing ` 构造函数的名称过滤器中的文件通配符模式将区分大小写进行匹配（详情请参阅 `QDir::setNameFilters()`）。
QDirListing::IteratorFlag::Recursive0x000400同时列出所有子目录中的条目。当与 FollowDirSymlinks 结合使用时，指向目录的符号链接也会被遍历。
QDirListing::IteratorFlag::FollowDirSymlinks0x000800与 Recursive 结合使用时，指向目录的符号链接也会被迭代。符号链接循环（例如，link => . 或 link => ..）会被自动检测并忽略。

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

成员函数文档

[explicit] QDirListing::QDirListing(const QString &path, QDirListing::IteratorFlags flags = IteratorFlag::Default)

构建一个 QDirListing，该对象可遍历path 。

您可以通过flags 传递选项，以控制目录的遍历方式。

默认情况下，flags 为IteratorFlag::Default 。

另请参阅 IteratorFlags 。

[explicit] QDirListing::QDirListing(const QString &path, const QStringList &nameFilters, QDirListing::IteratorFlags flags = IteratorFlag::Default)

创建一个 QDirListing 对象，该对象可遍历path 。

您可以通过flags 传递选项来控制目录的遍历方式。默认情况下，flags 的值为IteratorFlag::Default 。

列表中的条目将根据nameFilters 中的文件通配符模式进行过滤，这些模式会通过QRegularExpression::fromWildcard 转换为正则表达式（更多详情请参见QDir::setNameFilters()）。

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

QDirListing audioFileIt(u"/home/johndoe/"_s, QStringList{u"*.mp3"_s, u"*.wav"_s},
                        QDirListing::IteratorFlag::FilesOnly);

有时，通过使用 range-for 循环遍历条目并进行字符串比较，可以更高效地按名称进行过滤。例如：

    using F = QDirListing::IteratorFlag;
    const auto flags = F::FilesOnly | F::Recursive | F::ResolveSymlinks;
    for (const auto &dirEntry : QDirListing(u"/usr"_s, flags)) {
        // Faster than using name filters, filter ".txt" and ".html" files
        // using QString API
        const QString fileName = dirEntry.fileName();
        if (fileName.endsWith(".txt"_L1) || fileName.endsWith(".html"_L1)) {
            // ...
        }
    }
}

另请参阅 IteratorFlags 和QDir::setNameFilters()。

[noexcept] QDirListing::QDirListing(QDirListing &&other)

移动构造函数。将other 移动到此 QDirListing 中。

注意： 被移动的对象 other 将处于一种部分初始化的状态，在此状态下，唯一有效的操作是销毁和赋值。

[noexcept] QDirListing::~QDirListing()

销毁QDirListing 。

QDirListing::const_iterator QDirListing::begin() const

QDirListing::const_iterator QDirListing::cbegin() const

QDirListing::sentinel QDirListing::cend() const

QDirListing::sentinel QDirListing::end() const

(c)begin() 返回一个QDirListing::const_iterator ，可用于遍历目录条目。

  • 这是一个仅支持正向遍历、单遍历的迭代器（无法按逆序遍历目录条目）
  • 不可复制，仅支持 `std::move()d`。
  • 对实现std::input_iterator 的对象进行后递增运算的返回值是部分形成的（即一个已被推进的迭代器的副本），此类对象上唯一有效的操作是销毁和赋值一个新的迭代器。因此，后递增运算符会推进迭代器并返回void 。
  • 不允许随机访问
  • 可用于范围 for 循环；或与不要求随机访问迭代器的 C++20 std::ranges 算法配合使用
  • 对有效迭代器进行解引用将返回一个const DirEntry &
  • (c) `end()` 返回一个QDirListing::sentinel ，该值表示迭代结束。对与 `end()` 相等的迭代器进行解引用将导致未定义行为

注：每次 对同一个QDirListing 对象调用 (c)begin() 时，其内部状态都会被重置，迭代将重新开始。

（上述部分限制由底层系统库函数的实现所决定）。

例如：

usingItFlag=QDirListing::IteratorFlag;
for(const auto &dirEntry: QDirListing(u"/etc"_s,ItFlag::Recursive)) {
    qDebug() << dirEntry.filePath();
   // /etc/.
    // /etc/..
    // /etc/X11
    // /etc/X11/fs
    // ...
}

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

使用F=QDirListing::IteratorFlag;
QDirListing dirList(u"/sys"_s,QStringList{u"scaling_cur_freq"_s},F::FilesOnly|F::Recursive);
for(const auto &dirEntry: dirList) {
    QFile f(dirEntry.filePath());
    if(f.open(QIODevice::ReadOnly))
        qDebug() << f.fileName() << f.readAll().trimmed().toDouble() / 1000 << "MHz";
}

注意： “经典”的 STL 算法不支持迭代器/哨兵，因此您需要使用 C++20 的 std::ranges 算法来实现QDirListing ，或者使用在 C++17 中提供基于范围的算法的第三方库。

另请参阅 QDirListing::DirEntry 。

QDirListing::IteratorFlags QDirListing::iteratorFlags() const

返回用于构建此QDirListing 的IteratorFlags 集合。

QString QDirListing::iteratorPath() const

返回用于构建此QDirListing 的目录路径。

QStringList QDirListing::nameFilters() const

返回用于构建此QDirListing 的文件名通配符过滤器列表。

[noexcept] QDirListing &QDirListing::operator=(QDirListing &&other)

将other 移动并赋值给此QDirListing 。

注意： 被移动的对象 other 处于部分形成状态，在此状态下，唯一有效的操作是销毁和赋值。

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