当前位置：首页 > news >正文

Qt应用开发(基础篇)——文件选择对话框 QFileDialog

news 2026/3/31 10:15:24

一、前言

QFileDialog类继承于QDialog，提供了一个允许用户选择文件或目录的对话框。

对话框窗口 QDialog

QFileDialog文件选择对话框允许用户在当前文件系统中选择一个或者多个文件或者文件路径，使用静态函数创建是很简便的方式，比如：

QString fileName = QFileDialog::getOpenFileName(this,tr("Open Image"), "/home/jana", tr("Image Files (*.png *.jpg *.bmp)"));

在上面的例子的中，使用静态函数创建文件选择的模式对话框，分别传入标题、文件路径和文件过滤规则，比如你想要多个过滤器，那么用两个分号隔开。返回fileName为选择的文件名，如果没有选择则是空字符串。

"Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)"

当然我们也可以不使用静态函数创建，而是使用API创建，比如：

QFileDialog dialog(this);
dialog.setFileMode(QFileDialog::ExistingFile);
dialog.setNameFilter(tr("Image Files (*.png *.jpg *.bmp)"));
dialog.setWindowTitle("Open Image");
dialog.setDirectory("/home/jana");
QStringList fileNames;
if (dialog.exec())fileNames = dialog.selectedFiles();

在上面的实例中setFileMode()可以指定选择的是文件还是路径或者是全部都可以，使用setNameFilter()过滤文件类型，然后通过selectedFiles()得到选择的文件名称。

二、QFileDialog类

1、acceptMode

该属性表示对话框的操作策略，定义对话框是用于打开还是保存文件。默认为AcceptOpen，表示打开文件，另一个属性AcceptSave表示保存文件，相当于静态函数getOpen系列和getSave系列。

QFileDialog::AcceptMode acceptMode() const
void setAcceptMode(QFileDialog::AcceptMode mode)

2、defaultSuffix

该属性表示指定一个字符串，如果文件名没有后缀的话，则添加后文件名的后面。通常后缀是用来表示文件类型，比如txt表示文本，bin表示二进制文件，hex表示十六进制文件，ini表示配置文件等。

QString defaultSuffix() const
void setDefaultSuffix(const QString &suffix)

3、fileMode

该属性表示选择文件策略，定义了用户希望在对话框中选择的项的数量和类型。默认是AnyFile，该属性会影响文件选择时候的标签。

QFileDialog::FileMode fileMode() const
void setFileMode(QFileDialog::FileMode mode)

QFileDialog::FileMode 描述
QFileDialog::AnyFile 用户可以选择任何文件，甚至指定一个不存在的文件
QFileDialog::ExistingFile 用户只能选择单个存在的文件名称
QFileDialog::Directory 用户可以选择一个目录名称
QFileDialog::ExistingFiles 用户可以选择一个或者多个存在的文件名称

QFileDialog::FileMode	描述
QFileDialog::AnyFile	用户可以选择任何文件，甚至指定一个不存在的文件
QFileDialog::ExistingFile	用户只能选择单个存在的文件名称
QFileDialog::Directory	用户可以选择一个目录名称
QFileDialog::ExistingFiles	用户可以选择一个或者多个存在的文件名称

4、options

该属性表示影响对话框外观的各种选项，默认是没有的。

QFileDialog::Options options() const
void setOptions(QFileDialog::Options options)
void setOption(QFileDialog::Option option, bool on = true)

QFileDialog::Option 描述
ShowDirsOnly 文件对话框中只显示目录。默认情况下，同时显示文件和目录。(仅在目录文件模式下有效。)
DontResolveSymlinks 不要在文件对话框中解析符号链接。默认情况下，对符号链接进行解析。
DontConfirmOverwrite 如果选择了现有文件，请不要要求确认。默认情况下，请求确认。
DontUseNativeDialog 不要使用本机文件对话框。默认情况下，将使用本机文件对话框。

QFileDialog::Option	描述
ShowDirsOnly	文件对话框中只显示目录。默认情况下，同时显示文件和目录。(仅在目录文件模式下有效。)
DontResolveSymlinks	不要在文件对话框中解析符号链接。默认情况下，对符号链接进行解析。
DontConfirmOverwrite	如果选择了现有文件，请不要要求确认。默认情况下，请求确认。
DontUseNativeDialog	不要使用本机文件对话框。默认情况下，将使用本机文件对话框。

5、supportedSchemes

该属性表示文件对话框应该允许导航到的URL方案，设置此属性允许限制用户能够选择的url类型，设置为空字符串表示没有任何限制。

QStringList supportedSchemes() const
void setSupportedSchemes(const QStringList &schemes)

6、viewMode

该属性表示文件和目录在对话框中的显示方式，默认下，使用Detail模式显示文件和目录信息，另一个则为List模式仅显示目录中每个项目的图标和名称。

QFileDialog::ViewMode viewMode() const
void setViewMode(QFileDialog::ViewMode mode)

7、公共函数

1）directory

返回当前显示在对话框中的目录。

QDir directory() const

2）setDirectory

设置当前显示在对话框中的目录。

void setDirectory(const QString &directory)
void setDirectory(const QDir &directory)

3）directoryUrl

返回当前显示在对话框中的目录的url。

QUrl directoryUrl() const

4）setDirectoryUrl

设置当前显示在对话框中的目录的url。

void setDirectoryUrl(const QUrl &directory)

5）history

将文件对话框的浏览历史记录作为路径列表返回。

QStringList history() const

6）history

设置文件对话框的浏览历史记录以包含给定的路径。

void setHistory(const QStringList &paths)

7）iconProvider

返回文件对话框使用的图标，使用QFileIconProvider封装。

QFileIconProvider *iconProvider() const

8）setIconProvider

返回文件对话框使用的图标，使用QFileIconProvider封装。

void setIconProvider(QFileIconProvider *provider)

9）nameFilters

返回在此文件对话框上运行过滤器。

QStringList nameFilters() const

10）setNameFilters

设置在此文件对话框上运行过滤器。

void setNameFilters(const QStringList &filters)

 const QStringList filters({"Image files (*.png *.xpm *.jpg)","Text files (*.txt)","Any files (*)"});QFileDialog dialog(this);dialog.setNameFilters(filters);dialog.exec();

11）mimeTypeFilters

返回在此文件对话框上运行的MIME类型过滤器。

QStringList mimeTypeFilters() const

12）setMimeTypeFilters

设置在此文件对话框上运行的MIME类型过滤器。这是比setNameFilters更方便的方法，使用QMimeType从每个MIME类型中定义的全局模式和描述创建名称过滤器。

void setMimeTypeFilters(const QStringList &filters)

 QStringList mimeTypeFilters({"image/jpeg", // will show "JPEG image (*.jpeg *.jpg *.jpe)"image/png",  // will show "PNG image (*.png)""application/octet-stream" // will show "All files (*)"});QFileDialog dialog(this);dialog.setMimeTypeFilters(mimeTypeFilters);dialog.exec();

13）labelText

返回指定标签中文件对话框中显示的文本。

QString labelText(QFileDialog::DialogLabel label) const

14）labelText

设置指定标签中文件对话框中显示的文本。

void setLabelText(QFileDialog::DialogLabel label, const QString &text)

15）open

将它的一个信号连接到由接收器和成员指定的插槽。如果fileMode是ExistingFiles，则绑定filesSelected()信号，如果fileMode是其他任何东西，则绑定fileSelected()信号。当对话框关闭时，信号槽断开。

void open(QObject *receiver, const char *member)

16）proxyModel

返回文件对话框使用的QAbstractProxyModel代理模型。默认情况下，没有设置代理。

QAbstractProxyModel *proxyModel() const

17）setProxyModel

将视图的模型设置为给定的QAbstractProxyModel代理模型。用于修改底层模型，例如，添加列、筛选数据或添加驱动器。

void setProxyModel(QAbstractProxyModel *proxyModel)

18）itemDelegate

返回用于呈现文件对话框中视图中的项的项QAbstractItemDelegate委托。

QAbstractItemDelegate *itemDelegate() const

19）setItemDelegate

设置用于呈现文件对话框中视图中的项的项QAbstractItemDelegate委托。

void setItemDelegate(QAbstractItemDelegate *delegate)

20）restoreState

将对话框的布局、历史记录和当前目录恢复到指定的状态。

bool restoreState(const QByteArray &state)

21）saveState

保存对话框的布局、历史和当前目录的状态。一般返回QByteArray保存在外部文件或者缓存中，可以使用ini文件保存某一时刻的状态，然后必要的时候使用restoreState恢复到目标状态。

QByteArray saveState() const

22）selectedFiles

返回包含对话框中所选文件的绝对路径的字符串列表。如果没有选择文件，或者模式不是ExistingFiles或ExistingFile，则selectedFiles()包含视口中的当前路径。

QStringList selectedFiles() const

23）selectedFile

返回在文件对话框中选择给定的文件名。

void selectFile(const QString &filename)

24）selectedUrls

返回包含对话框中选定文件的url列表。如果没有选择文件，或者模式不是ExistingFiles或ExistingFile，则selectedUrls()包含视口中的当前路径。

QList<QUrl> selectedUrls() const

25）selectedNameFilter

返回用户在文件对话框中选择的过滤器。

QString selectedNameFilter() const

26）selectedMimeTypeFilter

返回用户在文件对话框中选择的文件的mime类型。

QString selectedMimeTypeFilter() const

27）sidebarUrls

返回位于侧边栏中的url。

QList<QUrl> sidebarUrls() const

28）setSidebarUrls

设置位于侧边栏中的url。

void setSidebarUrls(const QList<QUrl> &urls)

QList<QUrl> urls;
urls << QUrl::fromLocalFile("/Users/foo/Code/qt5")<< QUrl::fromLocalFile(QStandardPaths::standardLocations(QStandardPaths::MusicLocation).first());QFileDialog dialog;
dialog.setSidebarUrls(urls);
dialog.setFileMode(QFileDialog::AnyFile);
if(dialog.exec()) {// ...
}

8、静态函数

1）模式对话框

QFileDialog使用静态函数创建模式对话框，传入父窗口指针、标题、路径、窗口样式、过滤器，在父窗口居中显示，以下这些用法都大同小异，参考开头示例。

QString getExistingDirectory(QWidget *parent = nullptr, const QString &caption = QString(), const QString &dir = QString(), QFileDialog::Options options = ShowDirsOnly)
QUrl getExistingDirectoryUrl(QWidget *parent = nullptr, const QString &caption = QString(), const QUrl &dir = QUrl(), QFileDialog::Options options = ShowDirsOnly, const QStringList &supportedSchemes = QStringList())
void getOpenFileContent(const QString &nameFilter, const std::function<void (const QString &, const QByteArray &)> &fileOpenCompleted)
QString getOpenFileName(QWidget *parent = nullptr, const QString &caption = QString(), const QString &dir = QString(), const QString &filter = QString(), QString *selectedFilter = nullptr, QFileDialog::Options options = Options())
QStringList getOpenFileNames(QWidget *parent = nullptr, const QString &caption = QString(), const QString &dir = QString(), const QString &filter = QString(), QString *selectedFilter = nullptr, QFileDialog::Options options = Options())
QUrl getOpenFileUrl(QWidget *parent = nullptr, const QString &caption = QString(), const QUrl &dir = QUrl(), const QString &filter = QString(), QString *selectedFilter = nullptr, QFileDialog::Options options = Options(), const QStringList &supportedSchemes = QStringList())
QList<QUrl> getOpenFileUrls(QWidget *parent = nullptr, const QString &caption = QString(), const QUrl &dir = QUrl(), const QString &filter = QString(), QString *selectedFilter = nullptr, QFileDialog::Options options = Options(), const QStringList &supportedSchemes = QStringList())
QString getSaveFileName(QWidget *parent = nullptr, const QString &caption = QString(), const QString &dir = QString(), const QString &filter = QString(), QString *selectedFilter = nullptr, QFileDialog::Options options = Options())
QUrl getSaveFileUrl(QWidget *parent = nullptr, const QString &caption = QString(), const QUrl &dir = QUrl(), const QString &filter = QString(), QString *selectedFilter = nullptr, QFileDialog::Options options = Options(), const QStringList &supportedSchemes = QStringList())

2）saveFileContent

让用户选择的文件名和位置将fileContent保存到文件中，提供fileNameHint来向用户建议文件名。

void saveFileContent(const QByteArray &fileContent, const QString &fileNameHint = QString())

9、信号

1）currentChanged

当当前文件因本地操作而更改时，将发出此信号，并将新文件名作为路径参数。

void currentChanged(const QString &path)

2）currentUrlChanged

当当前文件发生变化时，该信号将以新文件URL作为URL参数发出。

void currentUrlChanged(const QUrl &url)

3）directoryEntered

当用户进入目录时，为本地操作发出此信号。

void directoryEntered(const QString &directory)

4）directoryUrlEntered

当用户进入目录时发出此信号。

void directoryUrlEntered(const QUrl &directory)

5）fileSelected

当本地操作的选择发生变化并且对话框被接受时，该信号将与所选文件(可能为空)一起发出。

void fileSelected(const QString &file)

6）filesSelected

当本地操作的选择发生变化并且接受对话框时，该信号将与所选文件的(可能为空的)列表一起发出。

 void filesSelected(const QStringList &selected)

7）filterSelected

当用户选择过滤器时，会发出此信号。

void filterSelected(const QString &filter)

8）urlSelected

当选择更改并且接受对话框时，该信号将与所选url(可能为空)一起发出。

void urlSelected(const QUrl &url)

9）urlsSelected

当选择更改并且接受对话框时，将发出此信号，其中包含所选url的列表(可能为空)。

void urlsSelected(const QList<QUrl> &urls)