一、描述 

QFileDialog 类使用户能够遍历文件系统以选择一个或多个文件或目录。

创建 QFileDialog 最简单的方法是使用静态函数：

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

在上面的示例中，模态 QFileDialog 是使用静态函数创建的。 该对话框最初显示“/home/jana”目录的内容，并显示与字符串“Image Files (*.png *.jpg *.bmp)”中给出的模式匹配的文件。

如果要使用多个过滤器，请用两个分号分隔每个过滤器。 例如：

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

可以在不使用静态函数的情况下创建自己的 QFileDialog。 通过调用 setFileMode()，可以指定用户必须在对话框中选择的内容：

QFileDialog dialog(this);
dialog.setFileMode(QFileDialog::AnyFile);

在上面的例子中，文件对话框的模式设置为 AnyFile，这意味着用户可以选择任何文件，甚至可以指定一个不存在的文件。此模式对于创建“另存为”文件对话框很有用。

fileMode 属性包含对话框的操作模式，这表明用户应该选择什么类型的对象。使用 setNameFilter() 设置文件过滤器。例如：

dialog.setNameFilter(tr("Images (*.png *.xpm *.jpg)"));

在上面的示例中，过滤器设置为“Images (*.png *.xpm *.jpg)”，这意味着只有扩展名为 png、xpm 或 jpg 的文件才会显示在 QFileDialog 中。可以使用 setNameFilters() 应用多个过滤器。使用 selectNameFilter() 选择提供的过滤器之一作为文件对话框的默认过滤器。

文件对话框有两种查看模式：列表和详细信息：

  • 列表将当前目录的内容显示为文件和目录名称的列表。
  • 详细信息还显示文件和目录名称列表，但在每个名称旁边提供附加信息，例如文件大小和修改日期。

使用 setViewMode() 设置模式：

dialog.setViewMode(QFileDialog::Detail);

创建自己的文件对话框时需要使用的最后一个重要函数是 selectedFiles()。

QStringList fileNames;
if (dialog.exec())
    fileNames = dialog.selectedFiles();

在上面的示例中，创建并显示了一个模态文件对话框。如果用户单击确定，他们选择的文件将放入 fileName时。

默认情况下，如果平台有一个平台原生文件对话框，则将使用它。在这种情况下，用于构造对话框的小部件将不会被实例化。可以设置 DontUseNativeDialog 选项以确保将使用基于小部件的实现而不是本机对话框。

二、类型成员

1、enum QFileDialog::AcceptMode

  • AcceptOpen：打开文件
  • AcceptSave：保存文件

2、enum QFileDialog::DialogLabel：对话框中的标签，可使用 setLabelText() 设置标签上的文本。

  • LookIn
  • FileName
  • FileType
  • Accept
  • Reject    

3、enum QFileDialog::FileMode：此枚举用于指示用户可以在文件对话框中选择什么，即如果用户单击确定，对话框将返回什么。

  • AnyFile：文件名，不管它是否存在。
  • ExistingFile：单个现有文件的名称。
  • Directory：目录的名称。 显示文件和目录。
  • ExistingFiles：零个或多个现有文件的名称。

4、enum QFileDialog::Option

  • ShowDirsOnly：只在文件对话框中显示目录。（仅在目录文件模式（Directory）下有效。）
  • DontResolveSymlinks：不解析文件对话框中的符号链接。
  • DontConfirmOverwrite：如果选择了现有文件，则不要求确认。
  • DontUseNativeDialog：不要使用本机文件对话框。
  • ReadOnly：表示模型是只读的。
  • HideNameFilterDetails：指示文件名过滤器详细信息是否隐藏。
  • DontUseCustomDirectoryIcons：始终使用默认目录图标。

5、enum QFileDialog::ViewMode：这个枚举描述了文件对话框的视图模式，即将显示有关每个文件的哪些信息。

  • Detail：显示目录中每个项目的图标、名称和详细信息。
  • List：仅显示目录中每个项目的图标和名称。

三、属性成员

1、acceptMode : AcceptMode

对话框的接受模式。默认为 AcceptOpen。

2、defaultSuffix : QString

默认后缀。

此属性指定一个字符串，它将被添加到文件名中。后缀通常用于表示文件类型（例如“txt”表示文本文件）。

如果第一个字符是点 ('.')，则将其删除。

3、fileMode : FileMode

对话框的文件模式。文件模式定义了用户希望在对话框中选择的项目的数量和类型。

默认为 AnyFile。

4、options : Options

影响对话框外观的各种选项。默认情况下，所有选项都被禁用。

选项应在显示对话框之前设置。

5、supportedSchemes : QStringList

文件对话框应允许导航到的 URL 方案。

6、viewMode : ViewMode

文件和目录在对话框中的显示方式。

四、静态成员函数

1、QString getExistingDirectory(QWidget *parent = nullptr, const QString &caption = QString(), const QString &dir = QString(), QFileDialog::Options options = ShowDirsOnly)

返回用户选择的现有目录。

创建一个模态文件对话框。如果 parent 不是 nullptr，则对话框将显示在父小部件的中心。

对话框的工作目录设置为 dir，标题设置为 caption 。其中任何一个都可能是空字符串，在这种情况下，将分别使用当前目录和默认标题。

警告：在对话框执行期间不要删除父级。如果想这样做，应该使用 QFileDialog 构造函数自己创建对话框。

QString dir = QFileDialog::getExistingDirectory(this, tr("Open Directory"),
                                                "/home",
                                                QFileDialog::ShowDirsOnly
                                                | QFileDialog::DontResolveSymlinks);

2、QUrl getExistingDirectoryUrl(QWidget *parent = nullptr, const QString &caption = QString(), const QUrl &dir = QUrl(), QFileDialog::Options options = ShowDirsOnly, const QStringList &supportedSchemes = QStringList())

返回用户选择的现有目录。如果用户按下取消，它会返回一个空的 url。

与 getExistingDirectory() 的主要区别在于提供给用户选择远程目录的能力。这就是为什么返回类型和 dir 的类型是 QUrl。

supportedSchemes 参数允许限制用户可以选择的 URL 类型。这是应用程序声明它将支持获取文件内容的协议的一种方式。空列表意味着不应用任何限制（默认）。支持本地文件（“文件”方案）是隐式的并且始终启用；没有必要将其包括在限制中。

3、void getOpenFileContent(const QString &nameFilter, const std::function<void (const QString &, const QByteArray &)> &fileOpenCompleted)

返回用户选择的文件的内容。

该函数是异步的并立即返回。当一个文件被选中并且它的内容被读入内存时，fileOpenCompleted 回调将被调用。

auto fileContentReady = [](const QString &fileName, const QByteArray &fileContent) 
{
    if (fileName.isEmpty()) 
    {
        // 未选择文件
    } 
    else 
    {
        // 使用文件名和文件内容
    }
};
QFileDialog::getOpenFileContent("Images (*.png *.xpm *.jpg)",  fileContentReady);

4、QString getOpenFileName(QWidget *parent = nullptr, const QString &caption = QString(), const QString &dir = QString(), const QString &filter = QString(), QString *selectedFilter = nullptr, QFileDialog::Options options = Options())

返回用户选择的现有文件。如果用户按下取消，它会返回一个空字符串。

QString fileName = QFileDialog::getOpenFileName(this, tr("Open File"),
                                                "/home",
                                                tr("Images (*.png *.xpm *.jpg)"));

该函数使用给定的父小部件创建一个模态文件对话框。如果 parent 不是 nullptr，则对话框将显示在父小部件的中心。

文件对话框的工作目录将设置为 dir。如果 dir 包含文件名，则将选择该文件。仅显示与 filter 匹配的文件。选择的过滤器设置为 selectedFilter。参数 dir、selectedFilter 和 filter 可以是空字符串。 如果想要多个过滤器，请将它们用 ';;' 分隔，例如：

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

对话框的标题设置为 caption 。如果未指定标题，则将使用默认标题。

警告：在对话框执行期间不要删除父级。如果想这样做，应该使用 QFileDialog 构造函数自己创建对话框。

5、QStringList getOpenFileNames(QWidget *parent = nullptr, const QString &caption = QString(), const QString &dir = QString(), const QString &filter = QString(), QString *selectedFilter = nullptr, QFileDialog::Options options = Options( ))

返回用户选择的一个或多个现有文件。

QStringList files = QFileDialog::getOpenFileNames(
                        this,
                        "Select one or more files to open",
                        "/home",
                        "Images (*.png *.xpm *.jpg)");

6、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())

返回用户选择的现有文件。如果用户按下取消，它会返回一个空的 url。

与 getOpenFileName() 的主要区别在于提供给用户选择远程文件的能力。这就是为什么返回类型和 dir 的类型是 QUrl。

supportedSchemes 参数允许限制用户可以选择的 URL 类型。这是应用程序声明它将支持获取文件内容的协议的一种方式。空列表意味着不应用任何限制（默认）。支持本地文件（“文件”方案）是隐式的并且始终启用；没有必要将其包括在限制中。

7、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())

返回用户选择的一个或多个现有文件。如果用户按下取消，它会返回一个空列表。

与 getOpenFileNames() 的主要区别在于提供给用户选择远程文件的能力。这就是为什么返回类型和 dir 的类型分别是 QList<QUrl> 和 QUrl。

supportedSchemes 参数允许限制用户可以选择的 URL 类型。这是应用程序声明它将支持获取文件内容的协议的一种方式。空列表意味着不应用任何限制（默认）。支持本地文件（“文件”方案）是隐式的并且始终启用；没有必要将其包括在限制中。

8、QString getSaveFileName(QWidget *parent = nullptr, const QString &caption = QString(), const QString &dir = QString(), const QString &filter = QString(), QString *selectedFilter = nullptr, QFileDialog::Options options = Options( ))

返回用户选择的文件名。该文件不必存在。

QString fileName = QFileDialog::getSaveFileName(this, tr("Save File"), 
                                                "/home/jana/untitled.png", 
                                                tr("Images (*.png *.xpm *.jpg)"));

9、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())

返回用户选择的文件。该文件不必存在。如果用户按下取消，它会返回一个空的 url。

与 getSaveFileName() 的主要区别在于提供给用户选择远程文件的能力。这就是为什么返回类型和 dir 的类型是 QUrl。

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

使用用户选择的文件名和位置将文件内容保存到文件中。 可以提供 fileNameHint 以向用户建议文件名。

该函数是异步的并立即返回。

QByteArray imageData;
QFileDialog::saveFile("myimage.png", imageData);

五、非静态成员函数

1、【信号】void currentChanged(const QString &path)

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

2、【信号】void currentUrlChanged(const QUrl &url)

当当前文件更改时，会发出此信号，并将新文件 URL 作为 url 参数。

3、【信号】void directoryEntered(const QString & directory )

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

4、【信号】void directoryUrlEntered(const QUrl & directory )

当用户进入目录时会发出这个信号。

5、【信号】void fileSelected(const QString & file)

当本地操作的选择发生变化并且对话框被接受时，该信号与选定文件一起发出。 

6、【信号】void  filesSelected(const QStringList & selected)

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

7、【信号】void filterSelected(const QString & filter)

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

8、【信号】void urlSelected(const QUrl & url)

当选择更改且对话框被接受时，此信号将与所选 url 一起发出。

9、【信号】void urlsSelected(const QList < QUrl > & urls)

当选择更改且对话框被接受时，此信号将与所选 URL 列表一起发出。

10、QDir directory()

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

11、QUrl directoryUrl()

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

12、QDir::Filters filter()

返回显示文件时使用的过滤器。

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

此函数将其信号之一连接到接收者和成员指定的槽。 如果 fileMode 是 ExistingFiles，信号是 filesSelected()，否则信号是 fileSelected()。

当对话框关闭时，信号将与槽断开连接。

14、bool restoreState(const QByteArray &state)

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

通常这与 QSettings 结合使用以恢复过去会话的大小。

如果有错误返回 false。

15、QByteArray saveState()

保存对话框布局、历史和当前目录的状态。

通常这与 QSettings 结合使用以记住未来会话的大小。

16、void selectFile(const QString &filename)

选择给定的文件名。

17、void selectMimeTypeFilter(const QString &filter)

设置当前的 MIME 类型过滤器。

18、void selectNameFilter(const QString &filter)

设置当前文件类型过滤器。通过用分号或空格分隔多个过滤器，可以在过滤器中传递多个过滤器。

19、void selectUrl(const QUrl &url)

在文件对话框中选择给定的 url。

非原生 QFileDialog 仅支持本地文件。

20、QStringList selectedFiles()

返回包含对话框中选定文件的绝对路径的列表。

21、QList<QUrl> selectedUrls()

返回包含对话框中选定文件的 url 列表。

22、void setDirectory(const QString &directory)

       void setDirectory(const QDir &directory)

设置文件对话框的当前目录。

23、void setDirectoryUrl(const QUrl &directory)

设置文件对话框的当前目录 url。

24、void setFilter(QDir::Filters filters)

设置过滤器。过滤器用于指定应显示的文件类型。

25、void setHistory(const QStringList &paths)

设置文件对话框的浏览历史记录。 

26、void setIconProvider(QAbstractFileIconProvider *provider)

设置文件对话框使用的图标提供程序。

27、void setItemDelegate(QAbstractItemDelegate *delegate)

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

QFileDialog 不获取委托的所有权。

警告：不应在视图之间共享同一委托实例。 这样做可能会导致不正确或不直观的编辑行为，因为连接到给定委托的每个视图都可能收到 closeEditor() 信号，并尝试访问、修改或关闭已关闭的编辑器。

使用的模型是 QFileSystemModel。它具有自定义项目数据角色，由 Roles 枚举描述。

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

设置文件对话框中显示的文本。 

29、void setMimeTypeFilters(const QStringList &filters)

从 MIME 类型列表中设置文件对话框中使用的过滤器。

是 setNameFilters() 的便捷方法。使用 QMimeType 从每个 MIME 类型中定义的 glob 模式和描述创建名称过滤器。

application/octet-stream 用于表示“所有文件 (*)”过滤器，因为这是所有文件的基本 MIME 类型。

QStringList mimeTypeFilters({"image/jpeg", // 将显示为： "JPEG image (*.jpeg *.jpg *.jpe)
                             "image/png",  // 将显示为： "PNG image (*.png)"
                             "application/octet-stream" // 将显示为： "All files (*)"
                            });

QFileDialog dialog(this);
dialog.setMimeTypeFilters(mimeTypeFilters);
dialog.exec();

30、void setNameFilter(const QString &filter)

设置文件对话框中使用的过滤器。

如果过滤器包含一对括号，其中包含一个或多个文件名通配符模式，以空格分隔，则仅将括号中包含的文本用作过滤器。这意味着这些调用都是等价的：

dialog.setNameFilter("All C++ files (*.cpp *.cc *.C *.cxx *.c++)");
dialog.setNameFilter("*.cpp *.cc *.C *.cxx *.c++");

31、void setNameFilters(const QStringList &filters)

设置文件对话框中使用的过滤器。

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

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

setMimeTypeFilters() 具有为每种文件类型提供所有可能的名称过滤器的优点。例如，JPEG 图像具有三种可能的扩展名；如果应用程序可以打开此类文件，则选择 image/jpeg mime 类型作为过滤器将允许打开所有这些文件。

32、void setOption(QFileDialog::Option option, bool on = true)

启用或清除选项。

选项（特别是 DontUseNativeDialogs 选项）应在更改对话框属性或显示对话框之前设置。

在对话框可见时设置选项不能保证立即对对话框产生影响（取决于选项和平台）。

33、void setProxyModel(QAbstractProxyModel *proxyModel)

设置代理模型。如果想修改底层模型，这很有用，例如，添加列、过滤数据等。

34、void setSidebarUrls(const QList<QUrl> &urls)

设置位于侧边栏中的 url。

例如：

    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()) {
        // ...
    }

35、bool testOption(QFileDialog::Option option)

是否启用了给定选项。

推荐内容
阅读全文
AI总结
# qt
Logo
GitCode 开源社区

旨在为数千万中国开发者提供一个无缝且高效的云端环境，以支持学习、使用和贡献开源项目。

更多推荐

cover

大学生摸鱼暂停！G-Star 校园开发者计划，喊你上车啦?

avatar GitCode 开源社区
cover

G-Star 校园开发者计划·黑科大｜开源第一课之 Git 入门

avatar GitCode 开源社区
cover

小胰宝 PancrePal 强势加入 GitCode！开启开源抗癌新纪元

avatar GitCode 开源社区