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

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

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

If enabled, the FileDialog will warn the user before overwriting files in save mode.

Equivalent to overwrite_warning_enabled.

Customization CUSTOMIZATION_DELETE = 8

If enabled, the context menu will show the "Delete" option, which allows moving files and folders to trash.

Equivalent to 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 🔗

If true, the context menu will show the "Delete" option, which allows moving files and folders to trash.

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

The available file type filters. Each filter string in the array should be formatted like this: *.png,*.jpg,*.jpeg;Image Files;image/png,image/jpeg. The description text of the filter is optional and can be omitted. Both file extensions and MIME type should be always set.

Note: Embedded file dialogs and Windows file dialogs support only file extensions, while Android, Linux, and macOS file dialogs also support MIME types.

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 🔗

If true, shows the button for creating new directories (when using FILE_MODE_OPEN_DIR, FILE_MODE_OPEN_ANY, or FILE_MODE_SAVE_FILE), and the context menu will have the "New Folder..." option.

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

bool overwrite_warning_enabled = true 🔗

If true, the FileDialog will warn the user before overwriting files in save mode.

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

If true, and if supported by the current DisplayServer, OS native dialog will be used instead of custom one.

Note: On Android, it is only supported for Android 10+ devices and when using ACCESS_FILESYSTEM. For access mode ACCESS_RESOURCES and ACCESS_USERDATA, the system will fall back to custom FileDialog.

Note: On Linux and macOS, sandboxed apps always use native dialogs to access the host file system.

Note: On macOS, sandboxed apps will save security-scoped bookmarks to retain access to the opened folders across multiple sessions. Use OS.get_granted_permissions() to get a list of saved bookmarks.

Note: Native dialogs are isolated from the base process, file dialog properties can't be modified once the dialog is shown.

Note: This property is ignored in EditorFileDialog.

方法说明

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

Adds a comma-separated file extension filter and comma-separated MIME type mime_type option to the FileDialog with an optional description, which restricts what files can be picked.

A filter should be of the form "filename.extension", where filename and extension can be * to match any string. Filters starting with . (i.e. empty filenames) are not allowed.

For example, a filter of "*.png, *.jpg", a mime_type of image/png, image/jpeg, and a description of "Images" results in filter text "Images (*.png, *.jpg)".

Note: Embedded file dialogs and Windows file dialogs support only file extensions, while Android, Linux, and macOS file dialogs also support MIME types.

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 🔗

Returns the list of favorite directories, which is shared by all FileDialog nodes. Useful to store the list of favorites between project sessions. This method can be called only from the main thread.

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 🔗

Returns the list of recent directories, which is shared by all FileDialog nodes. Useful to store the list of recents between project sessions. This method can be called only from the main thread.

Dictionary get_selected_options() const 🔗

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

VBoxContainer get_vbox() 🔗

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

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

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

void invalidate() 🔗

Invalidates and updates this dialog's content list.

Note: This method does nothing on native file dialogs.

bool is_customization_flag_enabled(flag: Customization) const 🔗

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

void popup_file_dialog() 🔗

Shows the FileDialog using the default size and position for file dialogs, and selects the file name if there is a current file.

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

Sets the specified customization flag, allowing to customize the features available in this FileDialog.

void set_favorite_list(favorites: PackedStringArray) static 🔗

Sets the list of favorite directories, which is shared by all FileDialog nodes. Useful to restore the list of favorites saved with get_favorite_list(). This method can be called only from the main thread.

Note: FileDialog will update its internal ItemList of favorites when its visibility changes. Be sure to call this method earlier if you want your changes to have effect.

void set_get_icon_callback(callback: Callable) static 🔗

Sets the callback used by the FileDialog nodes to get a file icon, when DISPLAY_LIST mode is used. The callback should take a single String argument (file path), and return a Texture2D. If an invalid texture is returned, the file icon will be used instead.

void set_get_thumbnail_callback(callback: Callable) static 🔗

Sets the callback used by the FileDialog nodes to get a file icon, when DISPLAY_THUMBNAILS mode is used. The callback should take a single String argument (file path), and return a Texture2D. If an invalid texture is returned, the file_thumbnail icon will be used instead.

Thumbnails are usually more complex and may take a while to load. To avoid stalling the application, you can use ImageTexture to asynchronously create the thumbnail.

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) # Some method that generates a thumbnail.
    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 🔗

Sets the list of recent directories, which is shared by all FileDialog nodes. Useful to restore the list of recents saved with set_recent_list(). This method can be called only from the main thread.

Note: FileDialog will update its internal ItemList of recent directories when its visibility changes. Be sure to call this method earlier if you want your changes to have effect.

主题属性说明

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

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

Texture2D reload 🔗

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

Texture2D sort 🔗

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

Texture2D thumbnail_mode 🔗

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

Texture2D toggle_filename_filter 🔗

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

Texture2D toggle_hidden 🔗

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