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
String	filename_filter	""
PackedStringArray	filters	PackedStringArray()
bool	mode_overrides_title	true
String	ok_button_text	"Save" (overrides AcceptDialog)
int	option_count	0
String	root_subfolder	""
bool	show_hidden_files	false
Vector2i	size	Vector2i(640, 360) (overrides Window)
String	title	"Save a File" (overrides Window)
bool	use_native_dialog	false

方法

void	add_filter(filter: String, description: String = "")
void	add_option(name: String, values: PackedStringArray, default_value_index: int)
void	clear_filename_filter()
void	clear_filters()
void	deselect_all()
LineEdit	get_line_edit()
int	get_option_default(option: int) const
String	get_option_name(option: int) const
PackedStringArray	get_option_values(option: int) const
Dictionary	get_selected_options() const
VBoxContainer	get_vbox()
void	invalidate()
void	set_option_default(option: int, default_value_index: int)
void	set_option_name(option: int, name: String)
void	set_option_values(option: int, values: PackedStringArray)

主题属性

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	create_folder
Texture2D	file
Texture2D	folder
Texture2D	forward_folder
Texture2D	parent_folder
Texture2D	reload
Texture2D	toggle_filename_filter
Texture2D	toggle_hidden

---

信号

dir_selected(dir: String) 🔗

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

---

file_selected(path: String) 🔗

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

---

filename_filter_changed(filter: String) 🔗

当文件名筛选器发生更改时发出。

---

files_selected(paths: PackedStringArray) 🔗

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

---

枚举

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 🔗

• void set_access(value: Access)

• Access get_access()

文件系统访问范围。请参阅 Access 常量。

警告：在 Web 构建中，FileDialog 无法访问主机文件系统。在沙盒 Linux 和 macOS 环境中，会自动使用 use_native_dialog 来允许对主机文件系统进行有限的访问。

---

String current_dir 🔗

• void set_current_dir(value: String)

• String get_current_dir()

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

注意：对于原生文件对话框，该属性仅被视为提示，并且可能不会被特定操作系统实现所遵守。

---

String current_file 🔗

• void set_current_file(value: String)

• String get_current_file()

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

---

String current_path 🔗

• void set_current_path(value: String)

• String get_current_path()

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

---

FileMode file_mode = 4 🔗

• void set_file_mode(value: FileMode)

• FileMode get_file_mode()

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

---

String filename_filter = "" 🔗

• void set_filename_filter(value: String)

• String get_filename_filter()

文件名筛选器（不区分大小写）。设置为非空字符串时，只会显示包含该子字符串的文件。用户可以通过文件对话框顶部的筛选按钮编辑 filename_filter。

另见 filters，应使用该属性限制可以选择的文件类型，而 filename_filter 则是由用户设置的。

---

PackedStringArray filters = PackedStringArray() 🔗

• void set_filters(value: PackedStringArray)

• PackedStringArray get_filters()

可用的文件类型筛选器。数组中筛选器字符串的格式应类似于：.png,.jpg,*.jpeg;图像文件;image/png,image/jpeg。筛选器的描述文本是可选的，可以省略。应始终设置文件扩展名和 MIME 类型。

注意：嵌入式文件对话框和 Windows 文件对话框仅支持文件扩展名，而 Android、Linux 和 macOS 文件对话框还支持 MIME 类型。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedStringArray for more details.

---

bool mode_overrides_title = true 🔗

• void set_mode_overrides_title(value: bool)

• bool is_mode_overriding_title()

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

---

int option_count = 0 🔗

• void set_option_count(value: int)

• int get_option_count()

对话框中附加的 OptionButton 和 CheckBox 的数量。

---

String root_subfolder = "" 🔗

• void set_root_subfolder(value: String)

• String get_root_subfolder()

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

注意：原生文件对话框将忽略该属性。

---

bool show_hidden_files = false 🔗

• void set_show_hidden_files(value: bool)

• bool is_showing_hidden_files()

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

注意：Android 和 Linux 上的原生文件对话框会忽略该属性。

---

bool use_native_dialog = false 🔗

• void set_use_native_dialog(value: bool)

• bool get_use_native_dialog()

如果为 true 并且当前 DisplayServer 支持原生对话框，那么就会使用操作系统原生对话框代替自定义对话框。

注意：在 Android 上只有使用 ACCESS_FILESYSTEM 时才支持。使用 ACCESS_RESOURCES、ACCESS_USERDATA 等访问模式时系统会回退至自定义 FileDialog。

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

注意：在 macOS 上，沙盒应用将保存安全范围的书签，以保留对跨多个会话打开的文件夹的访问权限。使用 OS.get_granted_permissions() 获取已保存书签的列表。

注意：原生对话框与基本进程隔离，对话框显示后，文件对话框属性无法修改。

---

方法说明

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

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

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

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

---

void add_option(name: String, values: PackedStringArray, default_value_index: int) 🔗

向文件对话框添加额外的 OptionButton。如果 values 为空，则添加的是 CheckBox。

default_value_index 应该是 values 的索引号。如果 values 为空，则应该是 1（选中）或 0（未选中）。

---

void clear_filename_filter() 🔗

清空文件名筛选器。

---

void clear_filters() 🔗

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

---

void deselect_all() 🔗

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

---

LineEdit get_line_edit() 🔗

返回所选文件的 LineEdit。

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

---

int get_option_default(option: int) const 🔗

返回索引为 option 的 OptionButton 或 CheckBox 的默认值索引。

---

String get_option_name(option: int) const 🔗

返回索引为 option 的 OptionButton 或 CheckBox 的名称。

---

PackedStringArray get_option_values(option: int) const 🔗

返回索引为 option 的 OptionButton 值的数组。

---

Dictionary get_selected_options() const 🔗

返回一个 Dictionary，其中包含附加 OptionButton 和/或 CheckBox 的选定值。Dictionary 的键是名称，而值是选定的值索引。

---

VBoxContainer get_vbox() 🔗

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

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

注意：原生文件对话框会忽略对该节点的更改，请使用 add_option() 向对话框添加自定义元素。

---

void invalidate() 🔗

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

注意：该方法对原生文件对话框不执行任何操作。

---

void set_option_default(option: int, default_value_index: int) 🔗

设置索引为 option 的 OptionButton 或 CheckBox 的默认值索引。

---

void set_option_name(option: int, name: String) 🔗

设置索引为 option 的 OptionButton 或 CheckBox 的名称。

---

void set_option_values(option: int, values: PackedStringArray) 🔗

设置索引为 option 的 OptionButton 的选项值。

---

主题属性说明

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 create_folder 🔗

用于创建文件夹按钮的自定义图标。

---

Texture2D file 🔗

文件的自定义图标。

---

Texture2D folder 🔗

文件夹的自定义图标。

---

Texture2D forward_folder 🔗

向前箭头的自定义图标。

---

Texture2D parent_folder 🔗

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

---

Texture2D reload 🔗

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

---

Texture2D toggle_filename_filter 🔗

切换隐藏文件名筛选器的自定义图标。

---

Texture2D toggle_hidden 🔗

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