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

派生： EditorFileDialog

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

描述

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

注意：FileDialog 默认情况下是隐藏的。若要显示，调用节点上来自 Window 的 popup_* 方法中的其中一个，比如 Window.popup_centered_clamped()。

属性

Access

access

0

String

current_dir

String

current_file

String

current_path

bool

deleting_enabled

true

bool

dialog_hide_on_ok

false (overrides AcceptDialog)

DisplayMode

display_mode

0

bool

favorites_enabled

true

bool

file_filter_toggle_enabled

true

FileMode

file_mode

4

bool

file_sort_options_enabled

true

String

filename_filter

""

PackedStringArray

filters

PackedStringArray()

bool

folder_creation_enabled

true

bool

hidden_files_toggle_enabled

true

bool

layout_toggle_enabled

true

bool

mode_overrides_title

true

int

option_count

0

int

option_{index}/default

0

String

option_{index}/name

""

PackedStringArray

option_{index}/values

PackedStringArray()

bool

overwrite_warning_enabled

true

bool

recent_list_enabled

true

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 = "", mime_type: String = "")

void

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

void

clear_filename_filter()

void

clear_filters()

void

deselect_all()

PackedStringArray

get_favorite_list() static

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

PackedStringArray

get_recent_list() static

Dictionary

get_selected_options() const

VBoxContainer

get_vbox()

void

invalidate()

bool

is_customization_flag_enabled(flag: Customization) const

void

popup_file_dialog()

void

set_customization_flag_enabled(flag: Customization, enabled: bool)

void

set_favorite_list(favorites: PackedStringArray) static

void

set_get_icon_callback(callback: Callable) static

void

set_get_thumbnail_callback(callback: Callable) static

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)

void

set_recent_list(recents: PackedStringArray) static

主题属性

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)

int

thumbnail_size

64

Texture2D

back_folder

Texture2D

create_folder

Texture2D

favorite

Texture2D

favorite_down

Texture2D

favorite_up

Texture2D

file

Texture2D

file_thumbnail

Texture2D

folder

Texture2D

folder_thumbnail

Texture2D

forward_folder

Texture2D

list_mode

Texture2D

menu_copy_path

Texture2D

menu_delete

Texture2D

menu_new_folder

Texture2D

menu_open_bundle

Texture2D

menu_refresh

Texture2D

menu_show_in_file_manager

Texture2D

parent_folder

Texture2D

reload

Texture2D

sort

Texture2D

thumbnail_mode

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

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

enum DisplayMode: 🔗

DisplayMode DISPLAY_THUMBNAILS = 0

该对话框以缩略图网格的形式显示文件。请使用 thumbnail_size 调整缩略图的大小。

DisplayMode DISPLAY_LIST = 1

该对话框以文件名列表的形式显示文件。

enum Customization: 🔗

Customization CUSTOMIZATION_HIDDEN_FILES = 0

切换收藏按钮是否可见，以及对话框左侧的收藏列表是否可见。

等价于 hidden_files_toggle_enabled。

Customization CUSTOMIZATION_CREATE_FOLDER = 1

如果启用，则会显示新建目录按钮（使用 FILE_MODE_OPEN_DIR、FILE_MODE_OPEN_ANY、FILE_MODE_SAVE_FILE 时有效）。

等价于 folder_creation_enabled。

Customization CUSTOMIZATION_FILE_FILTER = 2

如果启用，则会显示文件筛选开关按钮。

等价于 file_filter_toggle_enabled。

Customization CUSTOMIZATION_FILE_SORT = 3

如果启用，则会显示文件排序选项按钮。

等价于 file_sort_options_enabled。

Customization CUSTOMIZATION_FAVORITES = 4

如果启用，则会显示收藏开关按钮和对话框左侧的收藏列表。

等价于 favorites_enabled。

Customization CUSTOMIZATION_RECENT = 5

如果启用，则会显示对话框左侧的最近目录列表。

等价于 recent_list_enabled。

Customization CUSTOMIZATION_LAYOUT = 6

如果启用，则会显示布局切换按钮（列表、缩略图）。

等价于 layout_toggle_enabled。

Customization CUSTOMIZATION_OVERWRITE_WARNING = 7

如果启用，则 FileDialog 在保存模式下覆盖文件之前会向用户发出警告。

等价于 overwrite_warning_enabled。

Customization CUSTOMIZATION_DELETE = 8

如果启用，则上下文菜单将显示“删除”选项，允许将文件和文件夹移动到回收站。

等价于 deleting_enabled。

属性说明

Access access = 0 🔗

文件系统访问范围。

警告：在 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()

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

bool deleting_enabled = true 🔗

如果为 true，则上下文菜单将显示“删除”选项，允许将文件和文件夹移动到回收站。

DisplayMode display_mode = 0 🔗

对话框文件列表的显示模式。

bool favorites_enabled = true 🔗

如果为 true，则会显示收藏开关按钮和对话框左侧的收藏列表。

bool file_filter_toggle_enabled = true 🔗

如果为 true，则会显示文件筛选开关按钮。

FileMode file_mode = 4 🔗

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

bool file_sort_options_enabled = true 🔗

如果为 true，则会显示文件排序选项按钮。

String filename_filter = "" 🔗

  • void set_filename_filter(value: String)

  • String get_filename_filter()

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

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

PackedStringArray filters = PackedStringArray() 🔗

可用的文件类型筛选器。数组中筛选器字符串的格式应类似于：*.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 folder_creation_enabled = true 🔗

如果为 true，则会显示用于新建文件夹的按钮（适用于 FILE_MODE_OPEN_DIR、FILE_MODE_OPEN_ANY、FILE_MODE_SAVE_FILE），并且上下文菜单中会包含“新建文件夹...”选项。

bool hidden_files_toggle_enabled = true 🔗

如果为 true，则会显示隐藏文件开关按钮。

bool layout_toggle_enabled = true 🔗

如果为 true，则会显示布局切换按钮（列表、缩略图）。

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 的数量。

int option_{index}/default = 0 🔗

index 处选项的默认值。

注意： index 的取值范围为 0 .. option_count - 1。

String option_{index}/name = "" 🔗

index 处选项的名称。

注意： index 的取值范围为 0 .. option_count - 1。

PackedStringArray option_{index}/values = PackedStringArray() 🔗

index 处选项的值列表。

注意： index 的取值范围为 0 .. option_count - 1。

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

bool overwrite_warning_enabled = true 🔗

如果为 true，则在保存模式下，FileDialog 会在覆盖文件之前向用户发出警告。

bool recent_list_enabled = true 🔗

如果为 true，则会在对话框左侧显示最近目录列表。

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 平台上，沙盒应用会保存“安全作用域书签”（security-scoped bookmarks），以便在多次启动应用的会话之间，依然保留对已打开文件夹的访问权限。你可以使用 OS.get_granted_permissions() 方法来获取已保存的书签列表。

注意： 原生对话框与基础进程是相互隔离的，因此一旦对话框被弹出显示，就无法再修改它的属性了。

注意： 此属性在 EditorFileDialog（编辑器文件对话框）中会被直接忽略。

方法说明

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

将一个逗号分隔的文件扩展名 filter 和以逗号分隔的 MIME 类型 mime_type 的选项添加到 FileDialog，并可选择添加描述 description，用于限制可以选择的文件类型。

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

例如，如果 filter 为 "*.png, *.jpg"，mime_type 为 image/png, image/jpeg，description 为 "图像"，则生成的筛选器文本为“图像 (*.png, *.jpg)”。

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

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

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

PackedStringArray get_favorite_list() static 🔗

返回所有 FileDialog 节点共享的收藏目录列表。有利于在项目会话之间保存收藏列表。该方法只能从主线程中调用。

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 值的数组。

PackedStringArray get_recent_list() static 🔗

返回所有 FileDialog 节点共享的最近访问目录列表。有利于在项目会话之间保存最近访问的目录列表。该方法只能从主线程中调用。

Dictionary get_selected_options() const 🔗

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

VBoxContainer get_vbox() 🔗

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

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

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

void invalidate() 🔗

使该对话框的内容列表失效并更新。

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

bool is_customization_flag_enabled(flag: Customization) const 🔗

如果指定的 flag 已启用，则返回 true。

void popup_file_dialog() 🔗

使用文件对话框的默认大小和位置显示该 FileDialog，如果有当前文件则选择该文件名。

void set_customization_flag_enabled(flag: Customization, enabled: bool) 🔗

设置指定的自定义标志 flag，允许自定义该 FileDialog 的特性。

void set_favorite_list(favorites: PackedStringArray) static 🔗

设置所有 FileDialog 节点共享的收藏目录列表。有利于恢复使用 get_favorite_list() 保存的收藏列表。该方法只能从主线程中调用。

注意：FileDialog 在可见性发生变化时会更新其内部的收藏列表 ItemList。如果你希望你的更改生效，请务必提前调用该方法。

void set_get_icon_callback(callback: Callable) static 🔗

设置 FileDialog 节点在使用 DISPLAY_LIST 模式时获取文件图标所用的回调函数。该回调函数应接受一个 String 类型的参数（文件路径），并返回一个 Texture2D 对象。如果返回的纹理无效，则会改用 file 图标。

void set_get_thumbnail_callback(callback: Callable) static 🔗

设置 FileDialog 节点在使用 DISPLAY_THUMBNAILS 模式时获取文件图标所用的回调函数。该回调函数应接受一个 String 类型的参数（文件路径），并返回一个 Texture2D 对象。如果返回的纹理无效，则会改用 file_thumbnail 图标。

缩略图通常比较复杂，加载可能需要一些时间。为了避免应用程序卡顿，可以使用 ImageTexture 来异步创建缩略图。

func _ready():
    FileDialog.set_get_thumbnail_callback(thumbnail_method)

func thumbnail_method(path):
    var image_texture = ImageTexture.new()
    make_thumbnail_async(path, image_texture)
    return image_texture

func make_thumbnail_async(path, image_texture):
    var thumbnail_texture = await generate_thumbnail(path) # 某种用于生成缩略图的方法。
    image_texture.set_image(thumbnail_texture.get_image())

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 的选项值。

void set_recent_list(recents: PackedStringArray) static 🔗

设置由所有 FileDialog 节点共享的最近访问目录列表。有利于恢复使用 set_recent_list() 保存的最近访问列表。该方法只能从主线程中调用。

注意：FileDialog 在其可见性改变时会更新其内部的最近目录 ItemList。如果你希望你的更改生效，请务必尽早调用该方法。

主题属性说明

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

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

int thumbnail_size = 64 🔗

启用 DISPLAY_THUMBNAILS 时的缩略图图标大小。

Texture2D back_folder 🔗

向后箭头的自定义图标。

Texture2D create_folder 🔗

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

Texture2D favorite 🔗

收藏文件夹按钮得自定义图标。

Texture2D favorite_down 🔗

将收藏项向下移动的按钮的自定义图标。

Texture2D favorite_up 🔗

将收藏项向上移动的按钮的自定义图标。

Texture2D file 🔗

文件的自定义图标。

Texture2D file_thumbnail 🔗

缩略图模式下，文件的图标。

Texture2D folder 🔗

文件夹的自定义图标。

Texture2D folder_thumbnail 🔗

缩略图模式下，文件夹的图标。

Texture2D forward_folder 🔗

向前箭头的自定义图标。

Texture2D list_mode 🔗

用来启用列表模式的按钮的图标。

Texture2D menu_copy_path 🔗

"复制路径"上下文菜单选项的图标。

Texture2D menu_delete 🔗

"删除"上下文菜单选项的图标。

Texture2D menu_new_folder 🔗

“新建文件夹...”上下文菜单选项的图标。通常它应与 create_folder 保持一致；如果你希望上下文菜单不显示图标，请将其留空。

Texture2D menu_open_bundle 🔗

“显示包内容”上下文菜单选项的图标。该选项仅针对 macOS 程序包显示。

Texture2D menu_refresh 🔗

“刷新”上下文菜单选项的图标。通常它应与 reload 保持一致；如果你希望上下文菜单不显示图标，请将其留空。

Texture2D menu_show_in_file_manager 🔗

“在文件管理器中显示”上下文菜单选项的图标。

Texture2D parent_folder 🔗

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

Texture2D reload 🔗

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

Texture2D sort 🔗

排序选项按钮的自定义图标。

Texture2D thumbnail_mode 🔗

用来启用缩略图模式的按钮的图标。

Texture2D toggle_filename_filter 🔗

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

Texture2D toggle_hidden 🔗

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