Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

FileDialog

继承： ConfirmationDialog < AcceptDialog < Window < Viewport < Node < Object

用于选择文件系统中的文件或目录的对话框。

描述

FileDialog 是用来选择文件系统中文件和目录的预设对话框。支持过滤器掩码。FileDialog 会根据 file_mode 自动设置窗口的标题。如果你想使用自定义标题，请将 mode_overrides_title 设置为 false，禁用此功能。

属性

Access

access

0

String

current_dir

String

current_file

String

current_path

bool

dialog_hide_on_ok

false (overrides AcceptDialog)

FileMode

file_mode

4

PackedStringArray

filters

PackedStringArray()

bool

mode_overrides_title

true

String

root_subfolder

""

bool

show_hidden_files

false

String

title

"Save a File" (overrides Window)

bool

use_native_dialog

false

方法

void

add_filter ( String filter, String description="" )

void

clear_filters ( )

void

deselect_all ( )

LineEdit

get_line_edit ( )

VBoxContainer

get_vbox ( )

void

invalidate ( )

主题属性

Color

file_disabled_color

Color(1, 1, 1, 0.25)

Color

file_icon_color

Color(1, 1, 1, 1)

Color

folder_icon_color

Color(1, 1, 1, 1)

Texture2D

back_folder

Texture2D

file

Texture2D

folder

Texture2D

forward_folder

Texture2D

parent_folder

Texture2D

reload

Texture2D

toggle_hidden

信号

dir_selected ( String dir )

当用户选择一个目录时触发的。

file_selected ( String path )

当用户通过双击文件或按确定按钮选择一个文件时触发。

files_selected ( PackedStringArray paths )

当用户选择多个文件时触发。

枚举

enum FileMode:

FileMode FILE_MODE_OPEN_FILE = 0

该对话框只允许选择一个文件。

FileMode FILE_MODE_OPEN_FILES = 1

该对话框允许选择多个文件。

FileMode FILE_MODE_OPEN_DIR = 2

该对话框只允许选择一个目录，不允许选择任何文件。

FileMode FILE_MODE_OPEN_ANY = 3

该对话框允许选择一个文件或目录。

FileMode FILE_MODE_SAVE_FILE = 4

当文件存在时，对话框会发出警告。

enum Access:

Access ACCESS_RESOURCES = 0

该对话框只允许访问 Resource 路径下的文件（res://）。

Access ACCESS_USERDATA = 1

该对话框只允许访问用户数据路径（user://）下的文件。

Access ACCESS_FILESYSTEM = 2

该对话框允许访问文件系统上的文件。

属性说明

Access access = 0

文件系统的访问范围。见 Access 常量。

警告：目前，在 Web 构建或沙盒 macOS 应用程序等沙盒环境中，FileDialog 无法访问主机文件系统。参见 godot-proposals#1123。

String current_dir

  • void set_current_dir ( String value )

  • String get_current_dir ( )

文件对话框的当前工作目录。

String current_file

  • void set_current_file ( String value )

  • String get_current_file ( )

文件对话框的当前选定的文件。

String current_path

  • void set_current_path ( String value )

  • String get_current_path ( )

当前选择的文件对话框的文件路径。

FileMode file_mode = 4

对话框的打开或保存模式，会影响选择行为。见 FileMode。

PackedStringArray filters = PackedStringArray()

可用的文件类型过滤器。例如，这样就只会显示 .png 和 .gd 文件：set_filters(PackedStringArray(["*.png ; PNG Images","*.gd ; GDScript Files"]))。也可以在单个过滤器中指定多种文件类型。选中 "*.png, *.jpg, *.jpeg ; 支持的图片" 时，将同时显示 PNG 和 JPEG 文件。

bool mode_overrides_title = true

  • void set_mode_overrides_title ( bool value )

  • bool is_mode_overriding_title ( )

如果为 true，更改 file_mode 属性将相应地设置窗口标题（例如，将 file_mode 设置为 FILE_MODE_OPEN_FILE，会将窗口标题更改为“打开文件”）。

String root_subfolder = ""

  • void set_root_subfolder ( String value )

  • String get_root_subfolder ( )

如果非空，则给定的子文件夹将是该 FileDialog 的“根”，即用户将无法转到其父目录。

bool show_hidden_files = false

  • void set_show_hidden_files ( bool value )

  • bool is_showing_hidden_files ( )

如果为 true，对话框将显示出隐藏文件。

bool use_native_dialog = false

  • void set_use_native_dialog ( bool value )

  • bool get_use_native_dialog ( )

如果为 true，access 被设置为ACCESS_FILESYSTEM，并且它被当前的 DisplayServer 支持，则将使用操作系统原生对话框而不是自定义对话框。

注意：在 macOS 上，沙盒应用程序始终使用原生对话框来访问主机文件系统。

方法说明

void add_filter ( String filter, String description="" )

将一个逗号分隔的文件名 filter 且带有可选 description 的选项添加到的 FileDialog，这限制了可以选择的文件。

filter 的格式应为 "文件名.扩展名"，其中文件名和扩展名可以是 *，以匹配任意字符串。不允许使用以 . 开头的过滤器（即空文件名）。

例如，"*.png, *.jpg" 的 filter 和 "图像" 的 description 会产生过滤器文本“图像 (* .png, *.jpg)”。

void clear_filters ( )

清除对话框中所有添加的过滤器。

void deselect_all ( )

清除对话框中所有当前选定的项目。

LineEdit get_line_edit ( )

返回所选文件的 LineEdit。

警告：这是一个必需的内部节点，删除和释放它可能会导致崩溃。如果你希望隐藏它或其任何子项，请使用它们的 CanvasItem.visible 属性。

VBoxContainer get_vbox ( )

返回对话框的垂直框容器，可以向其中添加自定义控件。

警告：这是一个必需的内部节点，删除和释放它可能会导致崩溃。如果你希望隐藏它或其任何子项，请使用它们的 CanvasItem.visible 属性。

void invalidate ( )

使当前对话框内容列表无效并更新。

主题属性说明

Color file_disabled_color = Color(1, 1, 1, 0.25)

禁用文件的色调（当 FileDialog 在打开文件夹模式下使用时）。

Color file_icon_color = Color(1, 1, 1, 1)

应用于文件图标的颜色调制。

Color folder_icon_color = Color(1, 1, 1, 1)

应用于文件夹图标的颜色调制。

Texture2D back_folder

向后箭头的自定义图标。

Texture2D file

文件的自定义图标。

Texture2D folder

文件夹的自定义图标。

Texture2D forward_folder

向前箭头的自定义图标。

Texture2D parent_folder

父文件夹箭头的自定义图标。

Texture2D reload

重新加载按钮的自定义图标。

Texture2D toggle_hidden

切换隐藏按钮的自定义图标。