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)
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	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 = "")
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()
bool	is_customization_flag_enabled(flag: Customization) const
void	set_customization_flag_enabled(flag: Customization, enabled: bool)
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)`
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) 🔗

Emitted when the filter for file names changes.

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

The dialog displays files as a grid of thumbnails. Use thumbnail_size to adjust their size.

DisplayMode DISPLAY_LIST = 1

The dialog displays files as a list of filenames.

enum Customization: 🔗

Customization CUSTOMIZATION_HIDDEN_FILES = 0

Toggles visibility of the favorite button, and the favorite list on the left side of the dialog.

Equivalent to hidden_files_toggle_enabled.

Customization CUSTOMIZATION_CREATE_FOLDER = 1

If enabled, shows the button for creating new directories (when using FILE_MODE_OPEN_DIR, FILE_MODE_OPEN_ANY, or FILE_MODE_SAVE_FILE).

Equivalent to folder_creation_enabled.

Customization CUSTOMIZATION_FILE_FILTER = 2

If enabled, shows the toggle file filter button.

Equivalent to file_filter_toggle_enabled.

Customization CUSTOMIZATION_FILE_SORT = 3

If enabled, shows the file sorting options button.

Equivalent to file_sort_options_enabled.

Customization CUSTOMIZATION_FAVORITES = 4

If enabled, shows the toggle favorite button and favorite list on the left side of the dialog.

Equivalent to favorites_enabled.

Customization CUSTOMIZATION_RECENT = 5

If enabled, shows the recent directories list on the left side of the dialog.

Equivalent to recent_list_enabled.

Customization CUSTOMIZATION_LAYOUT = 6

If enabled, shows the layout switch buttons (list/thumbnails).

Equivalent to layout_toggle_enabled.

屬性說明

Access access = 0 🔗

void set_access(value: Access)
Access get_access()

The file system access scope.

Warning: In Web builds, FileDialog cannot access the host file system. In sandboxed Linux and macOS environments, use_native_dialog is automatically used to allow limited access to host file system.

String current_dir 🔗

void set_current_dir(value: String)
String get_current_dir()

The current working directory of the file dialog.

Note: For native file dialogs, this property is only treated as a hint and may not be respected by specific OS implementations.

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

目前選擇的檔對話方塊的檔路徑。

DisplayMode display_mode = 0 🔗

void set_display_mode(value: DisplayMode)
DisplayMode get_display_mode()

Display mode of the dialog's file list.

bool favorites_enabled = true 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

If true, shows the toggle favorite button and favorite list on the left side of the dialog.

bool file_filter_toggle_enabled = true 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

If true, shows the toggle file filter button.

FileMode file_mode = 4 🔗

void set_file_mode(value: FileMode)
FileMode get_file_mode()

The dialog's open or save mode, which affects the selection behavior.

bool file_sort_options_enabled = true 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

If true, shows the file sorting options button.

String filename_filter = "" 🔗

void set_filename_filter(value: String)
String get_filename_filter()

The filter for file names (case-insensitive). When set to a non-empty string, only files that contains the substring will be shown. filename_filter can be edited by the user with the filter button at the top of the file dialog.

See also filters, which should be used to restrict the file types that can be selected instead of filename_filter which is meant to be set by the user.

PackedStringArray filters = PackedStringArray() 🔗

void set_filters(value: PackedStringArray)
PackedStringArray get_filters()

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 dialog and Windows file dialog 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 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

If true, shows the button for creating new directories (when using FILE_MODE_OPEN_DIR, FILE_MODE_OPEN_ANY, or FILE_MODE_SAVE_FILE).

bool hidden_files_toggle_enabled = true 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

If true, shows the toggle hidden files button.

bool layout_toggle_enabled = true 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

If true, shows the layout switch buttons (list/thumbnails).

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

The number of additional OptionButtons and CheckBoxes in the dialog.

bool recent_list_enabled = true 🔗

void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const

If true, shows the recent directories list on the left side of the dialog.

String root_subfolder = "" 🔗

void set_root_subfolder(value: String)
String get_root_subfolder()

If non-empty, the given sub-folder will be "root" of this FileDialog, i.e. user won't be able to go to its parent directory.

Note: This property is ignored by native file dialogs.

bool show_hidden_files = false 🔗

void set_show_hidden_files(value: bool)
bool is_showing_hidden_files()

If true, the dialog will show hidden files.

Note: This property is ignored by native file dialogs on Android and 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.

方法說明

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

Adds a comma-separated file name filter 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" and a description of "Images" results in filter text "Images (*.png, *.jpg)".

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

Adds an additional OptionButton to the file dialog. If values is empty, a CheckBox is added instead.

default_value_index should be an index of the value in the values. If values is empty it should be either 1 (checked), or 0 (unchecked).

void clear_filename_filter() 🔗

Clear the filter for file names.

void clear_filters() 🔗

清除對話方塊中所有新增的篩檢程式。

void deselect_all() 🔗

清除對話方塊中所有目前選定的專案。

LineEdit get_line_edit() 🔗

返回所選檔案的 LineEdit。

警告：這是一個必需的內部節點，刪除和釋放它可能會導致當機。如果你希望隱藏它或其任何子項，請使用它們的 CanvasItem.visible 屬性。

int get_option_default(option: int) const 🔗

Returns the default value index of the OptionButton or CheckBox with index option.

String get_option_name(option: int) const 🔗

Returns the name of the OptionButton or CheckBox with index option.

PackedStringArray get_option_values(option: int) const 🔗

Returns an array of values of the OptionButton with index option.

Dictionary get_selected_options() const 🔗

Returns a Dictionary with the selected values of the additional OptionButtons and/or CheckBoxes. Dictionary keys are names and values are selected value indices.

VBoxContainer get_vbox() 🔗

Returns the vertical box container of the dialog, custom controls can be added to it.

Warning: This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their CanvasItem.visible property.

Note: Changes to this node are ignored by native file dialogs, use add_option() to add custom elements to the dialog instead.

void invalidate() 🔗

Invalidate and update the current dialog content list.

Note: This method does nothing on native file dialogs.

bool is_customization_flag_enabled(flag: Customization) const 🔗

Returns true if the provided flag is enabled.

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

Toggles the specified customization flag, allowing to customize features available in this FileDialog. See Customization for options.

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

Sets the default value index of the OptionButton or CheckBox with index option.

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

Sets the name of the OptionButton or CheckBox with index option.

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

Sets the option values of the OptionButton with index option.

主題屬性說明

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 🔗

The size of thumbnail icons when DISPLAY_THUMBNAILS is enabled.

Texture2D back_folder 🔗

向後箭頭的自訂圖示。

Texture2D create_folder 🔗

Custom icon for the create folder button.

Texture2D favorite 🔗

Custom icon for favorite folder button.

Texture2D favorite_down 🔗

Custom icon for button to move down a favorite entry.

Texture2D favorite_up 🔗

Custom icon for button to move up a favorite entry.

Texture2D file 🔗

檔的自訂圖示。

Texture2D file_thumbnail 🔗

Icon for files when in thumbnail mode.

Texture2D folder 🔗

資料夾的自訂圖示。

Texture2D folder_thumbnail 🔗

Icon for folders when in thumbnail mode.

Texture2D forward_folder 🔗

向前箭頭的自訂圖示。

Texture2D list_mode 🔗

Icon for the button that enables list mode.

Texture2D parent_folder 🔗

父資料夾箭頭的自訂圖示。

Texture2D reload 🔗

重新載入按鈕的自訂圖示。

Texture2D sort 🔗

Custom icon for the sorting options menu.

Texture2D thumbnail_mode 🔗

Icon for the button that enables thumbnail mode.

Texture2D toggle_filename_filter 🔗

Custom icon for the toggle button for the filter for file names.

Texture2D toggle_hidden 🔗

切換隱藏按鈕的自訂圖示。