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 за замовчуванням невидимий. Щоб зробити його видимим, викличте один із методів popup_* з Window на вузлі, наприклад, 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) 🔗

Увімкніть, коли користувач вибирає файл, натиснувши кнопку OK.

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 🔗

void set_access(value: Access)
Access get_access()

Область доступу до файлової системи.

Попередження: У веб-збірках 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 🔗

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

Якщо true, у контекстному меню відображатиметься опція «Видалити», яка дозволяє переміщувати файли та папки до кошика.

DisplayMode display_mode = 0 🔗

void set_display_mode(value: DisplayMode)
DisplayMode get_display_mode()

Режим відображення списку файлів у діалоговому вікні.

bool favorites_enabled = true 🔗

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

Якщо true, відображається кнопка перемикання обраного та список обраного у лівій частині діалогового вікна.

bool file_filter_toggle_enabled = true 🔗

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

Якщо true, відображається кнопка перемикання фільтра файлів.

FileMode file_mode = 4 🔗

void set_file_mode(value: FileMode)
FileMode get_file_mode()

Режим відкриття або збереження діалогового вікна, який впливає на поведінку вибору.

bool file_sort_options_enabled = true 🔗

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

Якщо true, відображається кнопка параметрів сортування файлів.

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 folder_creation_enabled = true 🔗

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

Якщо true, відображається кнопка для створення нових каталогів (при використанні FILE_MODE_OPEN_DIR, FILE_MODE_OPEN_ANY або 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

Якщо true, відображається кнопка перемикання прихованих файлів.

bool layout_toggle_enabled = true 🔗

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

Якщо true, відображається кнопка перемикання розкладки (список/мініатюри).

bool mode_overrides_title = true 🔗

void set_mode_overrides_title(value: bool)
bool is_mode_overriding_title()

Якщо true, змінивши пам'ятний файл_mode майно буде встановлено назву вікна відповідно (наприклад, налаштування file_mode до FILE_MODE_OPEN_FILE змінить назву вікна для "Відкрити файл").

int option_count = 0 🔗

void set_option_count(value: int)
int get_option_count()

Кількість додаткових OptionButtons і CheckBoxes в діалоговому вікні.

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 🔗

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

Якщо значення true, FileDialog попередить користувача перед перезаписом файлів у режимі збереження.

bool recent_list_enabled = true 🔗

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

Якщо значення 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 додатки в пісочниці зберігають закладки в межах безпеки, щоб зберегти доступ до відкритих папок у різних сесіях. Використовуйте OS.get_granted_permissions(), щоб отримати список збережених закладок.

Примітка: Вбудовані діалогові вікна ізольовані від базового процесу, властивості діалогового вікна файлів не можна змінити після його відображення.

Примітка: Ця властивість ігнорується в EditorFileDialog.

Описи методів

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

Додає розширення файлу filter, розділене комами, та MIME-тип mime_type, розділений комами, до FileDialog з необов'язковим параметром description, який обмежує вибір файлів.

filter повинен мати вигляд "filename.extension", де filename та extension можуть бути * для відповідності будь-якому рядку. Фільтри, що починаються з . (тобто пусті імена файлів), не допускаються.

Наприклад, filter з "*.png, *.jpg", mime_type з image/png, image/jpeg та description з "Images" призведе до тексту фільтра "Images (*.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() 🔗

Повертає рядок редагування для вибраного файлу.

Налаштування: Це необхідний внутрішній вузол, видаляючи і звільняючи його може призвести до аварії. Якщо ви хочете приховати його або будь-який з своїх дітей, скористайтеся їх CanvasItem.pic.

int get_option_default(option: int) const 🔗

Повертає значення за замовчуванням індексу OptionButton або CheckBox з індексом option.

String get_option_name(option: int) const 🔗

Повертає назву OptionButton або CheckBox з індексом option.

PackedStringArray get_option_values(option: int) const 🔗

Повертає масив значень OptionButton з індексом option.

PackedStringArray get_recent_list() static 🔗

Повертає список нещодавно використаних каталогів, який є спільним для всіх вузлів FileDialog. Корисно для зберігання списку нещодавно використаних каталогів між сеансами проекту. Цей метод можна викликати лише з головного потоку.

Dictionary get_selected_options() const 🔗

Повертає Dictionary з вибраними значеннями додаткових OptionButton та/або CheckBox. Ключі Dictionary – це імена, а значення – індекси вибраних значень.

VBoxContainer get_vbox() 🔗

Повертає вертикальний контейнер коробки діалогу, користувацькі елементи керування можна додавати до нього.

Попередження: Це необхідний внутрішній вузол, видаляючи і звільняючи його може призвести до аварії. Якщо ви хочете приховати його або будь-який з своїх дітей, скористайтеся їх CanvasItem.pic.

Примітка: Зміни до цієї вершини ігноруються рідними діалогами файлів, використовуйте add_option(), щоб додати користувацькі елементи до діалогу замість.

void invalidate() 🔗

Анулює та оновлює список вмісту цього діалогового вікна.

Примітка: Цей метод нічого не робить з діалоговими вікнами рідних файлів.

bool is_customization_flag_enabled(flag: Customization) const 🔗

Повертає true, якщо вказаний flag увімкнено.

Показує 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) # Some method that generates a thumbnail.
    image_texture.set_image(thumbnail_texture.get_image())

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

Встановлює індекс значення за замовчуванням для OptionButton або CheckBox з індексом option.

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

Встановлює назву OptionButton або CheckBox з індексом option.

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

Встановлює значення параметрів OptionButton з індексом option.

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 🔗

Піктограма кнопки, яка вмикає режим списку.

Піктограма для пункту контекстного меню «Копіювати шлях».

Піктограма для пункту контекстного меню «Видалити».

Піктограма для пункту контекстного меню «Нова папка...». Зазвичай вона повинна відповідати create_folder; залиште це поле порожнім, якщо хочете, щоб у контекстному меню не відображалися піктограми.

Піктограма для пункту контекстного меню «Показати вміст пакета». Цей пункт з’являється лише для пакетів macOS.

Піктограма для пункту контекстного меню «Оновити». Зазвичай вона повинна відповідати reload; залиште це поле порожнім, якщо хочете, щоб у контекстному меню не відображалися піктограми.

Піктограма для пункту контекстного меню «Показати у файловому менеджері».

Texture2D parent_folder 🔗

Користувальницькі іконки для стрілки папки батьків.

Texture2D reload 🔗

Настроювання іконки для кнопки перевантаження.

Texture2D sort 🔗

Спеціальна піктограма для меню параметрів сортування.

Texture2D thumbnail_mode 🔗

Піктограма кнопки, яка вмикає режим мініатюр.

Texture2D toggle_filename_filter 🔗

Настроювана піктограма для кнопки-перемикача фільтра імен файлів.

Texture2D toggle_hidden 🔗

Користувальницька ікона для окуляри прихована кнопка.