Back to Qt.io
Contact Us Blog Download Qt

FolderListModel QML Type

FolderListModel 提供了文件系统文件夹内容的模型。更多

Import Statement: import Qt.labs.folderlistmodel 2.9

属性

方法

详细描述

FolderListModel 可访问本地文件系统中文件夹的内容信息，向视图和其他数据组件提供文件列表。

注意： 该类型通过导入Qt.labs.folderlistmodel 模块可用。Qt.labs 模块中的元素不保证在未来版本中保持兼容。

注： FolderListModel 中的某些功能依赖于QFileSystemWatcher 。如果QFileSystemWatcher 被禁用，使用setFolder 设置的文件夹将不会被监视更改，这将导致通常在目录更改时发出的信号（如 directoryUpdated 或 directoryChanged）无法在不再次手动调用setFolder 的情况下发出。更多信息，请参阅Qt 配置选项。

import Qt.labs.folderlistmodel

folder 属性指定了要访问的文件夹。文件夹中的文件和目录信息通过模型接口提供。组件通过以下角色访问名称和路径：

  • fileName ( )string
  • filePath ( )string
  • fileURL ( ) （自 Qt 5.2 起；自 Qt 5.15 起已废弃）url
  • fileUrl ( ) （自 Qt 5.15 起弃用）url
  • fileBaseName ( )string
  • fileSuffix ( )string
  • fileSize ( )qlonglong
  • fileModified ( )date
  • fileAccessed ( )date
  • fileIsDir ( )bool

此外，还可以通过isFolder() 方法将文件条目与文件夹条目区分开来。

过滤

可以设置各种属性来过滤模型显示的文件和目录数量。

nameFilters 属性可设置为包含通配符过滤器列表，应用于文件和目录的名称，只暴露那些与过滤器匹配的文件和目录。

可以使用showDirs 属性包含或排除目录，也可以通过将showDotAndDotDot 属性设置为 false 来排除导航目录，还可以使用showHidden 属性包含或排除隐藏文件。

有时，将暴露的文件和目录限制为用户可以访问的文件和目录会很有用。可以设置showOnlyReadable 属性来启用这一功能。

使用示例

下面的示例显示了 FolderListModel 用于提供ListView 中的 QML 文件列表：

import QtQuick
import Qt.labs.folderlistmodel

ListView {
    width: 200; height: 400

    FolderListModel {
        id: folderModel
        nameFilters: ["*.qml"]
    }

    Component {
        id: fileDelegate
        required property string fileName
        Text { text: fileName }
    }

    model: folderModel
    delegate: fileDelegate
}

路径分隔符

Qt 使用"/"作为通用目录分隔符，就像 URL 中使用"/"作为路径分隔符一样。如果您总是使用"/"作为目录分隔符，Qt 将翻译您的路径以符合底层操作系统。

另请参阅 QML 数据模型。

属性文档

caseSensitive : bool

使用大小写敏感的模式匹配。

默认情况下，此属性为 true。


count : int [read-only]

返回当前文件夹中符合筛选条件的条目的数量。


folder : url

folder 属性包含模型当前提供的文件夹的 URL。

该值必须是file: 或qrc ：URL 或相对 URL。

默认值是FolderListModel 首次初始化时的应用程序工作目录。


nameFilters : list<string>

nameFilters 属性包含文件名过滤器列表。过滤器可包括 ? 和 * 通配符。

下面的示例过滤了 PNG 和 JPEG 文件：

FolderListModel {
    nameFilters: [ "*.png", "*.jpg" ]
}

注意： 过滤器不排除目录。


parentFolder : url [read-only]

返回当前folder 的父 URL。


rootFolder : url

设置此属性后，给定文件夹将被视为文件系统的根目录，因此只能遍历其中的子文件夹。


showDirs : bool

如果为 true，模型中将包含目录；否则只包含文件。

默认情况下，该属性为 true。

请注意，nameFilters 并不适用于目录。

另请参阅 showDotAndDotDot 。


showDirsFirst : bool

如果为 "true"，如果模型中包含目录，则总是先显示目录，然后显示文件。

默认情况下，此属性为假。


showDotAndDotDot : bool

如果为 "true"，模型中将包含". "和".. "目录；否则，它们将被排除在外。

默认情况下，此属性为 false。

另请参阅 showDirs 。


showFiles : bool

如果为 true，模型中包含文件；否则只包含目录。

默认情况下，此属性为 true。

另请参阅 showDirs 。


showHidden : bool

如果为 true，模型中将包含隐藏的文件和目录；否则将排除它们。

默认情况下，此属性为 false。


showOnlyReadable : bool

如果为 true，则只显示可读文件和目录；否则显示所有文件和目录。

默认情况下，此属性为 false。

另请参阅 showDirs 。


sortCaseSensitive : bool

如果设置为true ，则排序区分大小写。该属性默认为true 。


sortField : enumeration

sortField 属性包含用于排序的字段。sortField 可以是其中之一：

常量说明
FolderListModel.Unsorted不应用排序
FolderListModel.Name按文件名排序（默认）
FolderListModel.Time按修改时间排序
FolderListModel.Size按文件大小排序
FolderListModel.Type按文件类型/扩展名排序

另请参阅 sortReversed 。


sortReversed : bool

如果设置为 "true"，则会颠倒排序顺序。默认为假。

另请参阅 sortField 。


status : enumeration [read-only]

该属性用于保存文件夹的读取状态。它可以是

常量说明
FolderListModel.Null未设置folder
FolderListModel.Ready文件夹已加载
FolderListModel.Loading文件夹正在加载

使用此状态可提供更新或以某种方式响应状态变化。例如，您可以

  • 触发状态更改：
    State { name: 'loaded'; when: folderModel.status == FolderListModel.Ready }
  • 执行onStatusChanged 信号处理器：
    FolderListModel {
    id: folderModel
    onStatusChanged: if (folderModel.status == FolderListModel.Ready) console.log('Loaded')
}
  • 绑定状态值：
    Text { text: folderModel.status == FolderListModel.Ready ? 'Loaded' : 'Not loaded' }

方法文档

var get(int index, string property)

返回给定index 的文件夹property 。可使用以下属性：

  • fileName ( )string
  • filePath ( )string
  • fileURL ( ) （自 Qt 5.2 起；自 Qt 5.15 起已弃用）url
  • fileUrl ( ) (自 Qt 5.15 起)url
  • fileBaseName ( )string
  • fileSuffix ( )string
  • fileSize ( )qlonglong
  • fileModified ( )date
  • fileAccessed ( )date
  • fileIsDir ( )bool

int indexOf(url file)

如果模型包含给定的file URL，则返回该 URL 的索引；如果不包含，则返回-1。


bool isFolder(int index)

如果条目index 是文件夹，则返回 true；否则返回 false。


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