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, ExcludeSpecial, 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 构造函数的参数是目录路径字符串。下面是递归遍历所有条目的方法：

使用ItFlag=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；QDirListingdirList(u"/sys"_s、 QStringList{u"scaling_cur_freq"_s},F::FilesOnly|F::Recursive);for(const auto &dirEntry: dirList) { QFilef(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++20std::input_iterator，也就是说，它是一个只向前移动的单程迭代器，不允许随机访问。它可用于 ranged-for 循环（或不需要随机访问迭代器的 C++20 范围算法）。取消引用一个有效的迭代器会返回一个 对象。(c) () 哨兵标志着迭代的结束。取消引用等于 的迭代器是未定义的行为。QDirListing::DirEntryend 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()。

成员类型文档

枚举类 QDirListing::IteratorFlag
flags QDirListing::IteratorFlags

该枚举类描述了可用于配置QDirListing 行为的标志。该枚举器中的值可位相 OR。

常量值描述
QDirListing::IteratorFlag::Default0x000000列出所有文件、目录和符号链接，包括断开的符号链接（目标不存在）。默认情况下不列出隐藏文件和目录以及特殊条目. 和.. 。
QDirListing::IteratorFlag::ExcludeFiles0x000004不列出常规文件。与 ResolveSymlinks 结合使用时，指向常规文件的符号链接也会被排除。
QDirListing::IteratorFlag::ExcludeDirs0x000008不列出目录。与 ResolveSymlinks 结合使用时，也会排除指向目录的符号链接。
QDirListing::IteratorFlag::ExcludeSpecial0x000010不列出非目录、常规文件或符号链接的文件系统条目。
  • 在 Unix 上，特殊文件系统项的例子包括 FIFO、套接字、字符设备或块设备。有关 Linux 的更多详情，请参阅mknod 手册页面。
  • 在 Windows 中（由于历史原因），.lnk 文件被视为特殊文件系统项。
QDirListing::IteratorFlag::ResolveSymlinks0x000020根据链接目标的类型而非符号链接本身过滤符号链接。使用此标记，将排除已损坏的符号链接（目标不存在）。在不支持符号链接的操作系统上，该标记将被忽略。
QDirListing::IteratorFlag::FilesOnlyExcludeDirs | ExcludeSpecial只会列出常规文件。与 ResolveSymlinks 结合使用时，也会列出文件的符号链接。
QDirListing::IteratorFlag::DirsOnlyExcludeFiles | ExcludeSpecial只列出目录。与 ResolveSymlinks 结合使用时，也会列出目录的符号链接。
QDirListing::IteratorFlag::IncludeHidden0x000040列出隐藏条目。与递归相结合时，迭代也会递归到隐藏的子目录。
QDirListing::IteratorFlag::IncludeDotAndDotDot0x000080列出. 和.. 特殊条目。
QDirListing::IteratorFlag::CaseSensitive0x000100传递给QDirListing 构造函数的名称筛选器中的文件 glob 模式将区分大小写进行匹配（详情请参见QDir::setNameFilters()）。
QDirListing::IteratorFlag::Recursive0x000400同时列出所有子目录内的条目。与 FollowDirSymlinks 结合使用时，还将遍历目录的符号链接。
QDirListing::IteratorFlag::FollowDirSymlinks0x000800与 Recursive 结合使用时，也会遍历指向目录的符号链接。符号链接循环（如 link => .或 link => ..）会被自动检测并忽略。

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

成员函数文档

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 的对象，post-increment 的返回值是部分形成的（一个迭代器的副本，该迭代器已被向前推进），对这样的对象进行的唯一有效操作是销毁和分配一个新的迭代器。因此，post-increment 操作符将迭代器向前推进并返回void 。
  • 不允许随机访问
  • 可用于 ranged-for 循环；或用于不需要随机访问迭代器的 C++20 std::ranges 算法。
  • 取消引用一个有效的迭代器会返回一个const DirEntry &
  • (c)end() 返回一个表示迭代结束的QDirListing::sentinel 。取消引用一个比较等于end() 的迭代器是未定义的行为

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

(上述某些限制由底层系统库函数的实现决定）。

例如

使用ItFlag=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；QDirListingdirList(u"/sys"_s、 QStringList{u"scaling_cur_freq"_s},F::FilesOnly|F::Recursive);for(const auto &dirEntry: dirList) { QFilef(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 。

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

构造一个可以遍历path 的 QDirListing。

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

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

另请参见 IteratorFlags 。

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

构造一个可以遍历path 的 QDirListing。

您可以通过flags 传递选项，控制目录的迭代方式。默认情况下，flags 是IteratorFlag::Default 。

列出的条目将根据nameFilters 中的文件 glob 模式进行过滤（详情请参见QDir::setNameFilters() ）。

例如，以下迭代器可用来迭代音频文件：

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

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

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

移动构造函数。将other 移入此 QDirListing。

注意： 被移入的对象other 处于部分形成状态，其中唯一有效的操作是销毁和赋新值。

[noexcept] QDirListing::~QDirListing()

摧毁QDirListing.

QDirListing::IteratorFlags QDirListing::iteratorFlags() const

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

QString QDirListing::iteratorPath() const

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

QStringList QDirListing::nameFilters() const

返回用于构建QDirListing 的文件名 glob 过滤器列表。

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

移动将other 赋值给QDirListing 。

注： 从移动对象other 将处于部分形成状态，其中唯一有效的操作是销毁和赋新值。

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