Back to Qt.io
Contact Us Blog Download Qt

FileDialog QML Type

文件对话框。更多

Import Statement: import QtQuick.Dialogs
Since: Qt 6.2
Inherits:

Dialog

属性

详细说明

FileDialog 类型为文件对话框提供了 QML API。

文件对话框类型允许对话框复制平台的本地外观和感觉

要显示文件对话框，只需构建 FileDialog 的实例、设置所需的属性并调用open() 即可。currentFolder 属性可用于确定打开对话框的文件夹。selectedFile 和selectedFiles 属性可用于确定对话框打开时选择的文件，当用户在对话框中选择文件和接受对话框时，这两个属性也会更新。

import QtCore
import QtQuick
import QtQuick.Controls
import QtQuick.Dialogs

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    header: ToolBar {
        Button {
            text: qsTr("Choose Image...")
            onClicked: fileDialog.open()
        }
    }

    Image {
        id: image
        anchors.fill: parent
        fillMode: Image.PreserveAspectFit
    }

    FileDialog {
        id: fileDialog
        currentFolder: StandardPaths.standardLocations(StandardPaths.PicturesLocation)[0]
        onAccepted: image.source = selectedFile
    }
}

可用性

本机平台文件对话框目前在以下平台上可用：

  • 安卓
  • iOS
  • Linux（使用 GTK+ 平台主题运行时）
  • MacOS
  • Windows

Qt Quick Dialogs 在没有本地实现的平台上，使用 实现作为备用。Qt Quick

另请参阅 FolderDialog 和StandardPaths 。

属性文档

acceptLabel : string

该属性用于保存接受对话框的按钮上显示的标签文本。

当设置为空字符串时，将使用底层平台的默认标签。默认标签通常为Open 或Save ，具体取决于对话框在哪个fileMode 中使用。

默认值为空字符串。

另请参阅 rejectLabel 。


currentFolder : url

该属性用于保存选择文件的文件夹。设置该属性可控制打开对话框时显示的初始目录。

要选择文件夹，请使用FolderDialog 。


defaultSuffix : string

该属性包含一个后缀，会添加到未指定后缀的选定文件中。后缀通常用于表示文件类型（例如，"txt "表示文本文件）。

如果第一个字符是点（'.'），则会被删除。


fileMode : enumeration

该属性表示对话框的模式。

可用值：

常量说明
FileDialog.OpenFile对话框用于选择一个现有文件（默认）。
FileDialog.OpenFiles对话框用于选择多个现有文件。
FileDialog.SaveFile对话框用于选择任何文件。文件不一定存在。

nameFilters : list<string>

该属性包含限制可选择文件类型的筛选器。

FileDialog {
    nameFilters: ["Text files (*.txt)", "HTML files (*.html *.htm)"]
}

不同的平台可能会以不同的方式限制可选择的文件。例如，macOS 会禁用与筛选器不匹配的文件条目，而 Windows 则会隐藏它们。

注意： *.*并非可移植的筛选器，因为文件扩展名决定文件类型的历史假设在每个操作系统上都不一致。文件名中可能没有点（例如Makefile ）。在本地 Windows 文件对话框中，*.*将匹配此类文件，而在其他类型的文件对话框中则可能不匹配。因此，如果要选择任何文件，最好使用*。

另请参阅 selectedNameFilter 。


options : flags

该属性包含影响对话框外观的各种选项。

默认情况下，所有选项都是禁用的。

应在显示对话框之前设置选项。如果在对话框可见时设置这些选项，则不能保证会立即对对话框产生影响（取决于选项和平台）。

可用选项

常量说明
FileDialog.DontResolveSymlinks不在文件对话框中解析符号链接。默认情况下会解析符号链接。
FileDialog.DontConfirmOverwrite如果选择了现有文件，则不要求确认。默认情况下要求确认。
FileDialog.ReadOnly表示对话框不允许创建目录。
FileDialog.HideNameFilterDetails表示是否隐藏文件名过滤器详细信息。
FileDialog.DontUseNativeDialog强制对话框使用非本地快速实现。

rejectLabel : string

该属性用于保存拒绝对话框按钮上显示的标签文本。

如果设置为空字符串，则使用底层平台的默认标签。默认标签通常是Cancel 。

默认值为空字符串。

另请参阅 acceptLabel 。


selectedFile : url

该属性保存对话框中最后选择的文件。

设置该属性可控制打开对话框时选择的文件。

如果有多个选定文件，该属性指的是第一个文件。

每次用户在对话框中选择文件以及接受对话框时，该属性的值都会更新。处理accepted() 信号以获得最终选择。

另请参阅 selectedFiles 、accepted() 和currentFolder 。


selectedFiles : list<url>

该属性保存对话框中最后选择的文件。

每次用户在对话框中选择文件以及接受对话框时，该属性的值都会更新。处理accepted() 信号可获得最终选择。

另请参阅 accepted() 和currentFolder 。


selectedNameFilter group

selectedNameFilter.extensions : list<string>

selectedNameFilter.globs : list<string>

selectedNameFilter.index : int

selectedNameFilter.name : string

这些属性保存当前选择的名称过滤器。

名称名称
index: int该属性决定选择哪个name filter 。对话框打开时，指定的过滤器将被选中。当用户选择另一个过滤器时，该值将被更新。
[name: string此属性用于保存所选过滤器的名称。在下面的示例中，第一个过滤器的名称是"Text files" ，第二个过滤器的名称是"HTML files" 。
[只读]extensions: list<string> （扩展名）。此属性包含所选过滤器的扩展名列表。在下面的示例中，第一个过滤器的扩展名列表为["txt"] ，第二个过滤器的扩展名列表为["html", "htm"] 。
[只读]globs: list<string该属性包含所选过滤器的 globs 列表。在下面的示例中，第一个过滤器的 globs 列表是["*.txt"] ，第二个是["*.html", "*.htm"] 。

例如，该属性可与FolderListModel 的nameFilters 属性结合使用。

FileDialog {
    id: fileDialog
    selectedNameFilter.index: 1
    nameFilters: ["Text files (*.txt)", "HTML files (*.html *.htm)"]
}

MyDocument {
    id: document
    fileType: fileDialog.selectedNameFilter.extensions[0]
}

另请参阅 nameFilters 。


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