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...

DirAccess

Успадковує: RefCounted < Object

Забезпечує методи управління каталогами та їх змістом.

Опис

Цей клас використовується для керування каталогами та їхнім вмістом, навіть поза папкою проекту.

DirAccess не можна створити екземпляр безпосередньо. Натомість він створюється за допомогою статичного методу, який приймає шлях, для якого його буде відкрито.

Більшість методів мають статичну альтернативу, яку можна використовувати без створення DirAccess. Статичні методи підтримують лише абсолютні шляхи (включаючи res:// і user://).

# Стандарт
var dir = DirAccess.open("user://levels")
dir.make_dir("world1")
# Статичний
DirAccess.make_dir_absolute("user://levels/world1")

Примітка: Доступ до каталогів проекту ("res://") після експорту може поводитися неочікувано, оскільки деякі файли перетворюються на формати, що відповідають системі, і їхні оригінальні вихідні файли можуть не бути присутніми в очікуваному пакеті PCK. Через це для доступу до ресурсів в експортованому проекті рекомендується використовувати ResourceLoader замість FileAccess.

Ось приклад того, як перебирати файли каталогу:

[gdscript]
func dir_contents(path):
    var dir = DirAccess.open(path)
    if dir:
        dir.list_dir_begin()
        var file_name = dir.get_next()
        while file_name != "":
            if dir.current_is_dir():
                print("Знайдено каталог: " + ім'я_файлу)
            else:
                print("Знайдено файл: " + ім'я_файлу)
            nane_file = dir.get_next()
    ще:
        print("Під час спроби отримати доступ до шляху сталася помилка.")
[/gdscript]
[csharp]
public void DirContents (string path)
{
    використовуючи var dir = DirAccess.Open(path);
    if (dir != null)
    {
        dir.ListDirBegin();
        string fileName = dir.GetNext();
        while (fileName != "")
        {
            if (dir.CurrentIsDir())
            {
                GD.Print($"Знайдено каталог: {fileName}");
            }
            else
            {
                GD.Print($"Знайдено файл: {fileName}");
            }
            fileName = dir.GetNext();
        }
    }
    else
    {
        GD.Print("Під час спроби отримати доступ до шляху сталася помилка.");
    }
}
[/csharp] [/codeblocks]

Майте на увазі, що після експорту імена файлів можуть змінитися або бути повторно призначені. Якщо ви хочете побачити фактичний список файлів ресурсів, як він відображається в редакторі, замість цього використовуйте [method ResourceLoader.list_directory].

Посібники

Файлова система

Властивості

bool	include_hidden
bool	include_navigational

Методи

Error	change_dir(to_dir: String)
Error	copy(from: String, to: String, chmod_flags: int = -1)
Error	copy_absolute(from: String, to: String, chmod_flags: int = -1) static
Error	create_link(source: String, target: String)
DirAccess	create_temp(prefix: String = "", keep: bool = false) static
bool	current_is_dir() const
bool	dir_exists(path: String)
bool	dir_exists_absolute(path: String) static
bool	file_exists(path: String)
String	get_current_dir(include_drive: bool = true) const
int	get_current_drive()
PackedStringArray	get_directories()
PackedStringArray	get_directories_at(path: String) static
int	get_drive_count() static
String	get_drive_label(idx: int) static
String	get_drive_name(idx: int) static
PackedStringArray	get_files()
PackedStringArray	get_files_at(path: String) static
String	get_filesystem_type() const
String	get_next()
Error	get_open_error() static
int	get_space_left()
bool	is_bundle(path: String) const
bool	is_case_sensitive(path: String) const
bool	is_equivalent(path_a: String, path_b: String) const
bool	is_link(path: String)
Error	list_dir_begin()
void	list_dir_end()
Error	make_dir(path: String)
Error	make_dir_absolute(path: String) static
Error	make_dir_recursive(path: String)
Error	make_dir_recursive_absolute(path: String) static
DirAccess	open(path: String) static
String	read_link(path: String)
Error	remove(path: String)
Error	remove_absolute(path: String) static
Error	rename(from: String, to: String)
Error	rename_absolute(from: String, to: String) static

Описи властивостей

bool include_hidden 🔗

void set_include_hidden(value: bool)
bool get_include_hidden()

Якщо значення true, приховані файли враховуються під час навігації по каталогу.

Впливає на list_dir_begin(), get_directories() та get_files().

bool include_navigational 🔗

void set_include_navigational(value: bool)
bool get_include_navigational()

Якщо значення true, значення . та . включаються під час навігації по каталогу.

Впливає на метод list_dir_begin() та get_directories().

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

Error change_dir(to_dir: String) 🔗

Змінює в даний час відкритий каталог до одного переданого аргументу. Текст може бути відносно поточного каталогу (наприклад, newdir або ./newdir), або абсолютний шлях (наприклад, /tmp/newdir або res://somedir/newdir).

Повертаємо один з кодових констанцій (@GlobalScope.OK на успіх).

Примітка: Новий каталог має бути в межах тієї ж сфери, наприклад, коли ви відкрили каталог всередині res://, ви не можете змінити його на user:// каталог. Якщо вам необхідно відкрити каталог в іншій області доступу, скористайтеся open() для створення нового екземпляра замість.

Error copy(from: String, to: String, chmod_flags: int = -1) 🔗

Скопіює файл from до to призначення. Обидва аргументи повинні бути шляхами до файлів, або відносних або абсолютного. Якщо файл призначення існує і не захищений доступ, він буде перезаписати.

Якщо chmod_flags відрізняється від -1, Унікс дозволів на шлях призначення буде встановлена на задану вартість, якщо доступна на поточній операційній системі.

Повертаємо один з кодових констанцій (@GlobalScope.OK на успіх).

Error copy_absolute(from: String, to: String, chmod_flags: int = -1) static 🔗

Статична версія copy(). Підтримує лише абсолютні шляхи.

Error create_link(source: String, target: String) 🔗

Створення символічного посилання між файлами або папками.

Примітка: На Windows, цей метод працює тільки якщо додаток працює з підвищеними привілеями або режимом розробника.

Примітка: Цей метод реалізується на macOS, Linux та Windows.

DirAccess create_temp(prefix: String = "", keep: bool = false) static 🔗

Створює тимчасовий каталог. Цей каталог буде звільнено, коли буде звільнено повернутий DirAccess.

Якщо prefix не порожній, він буде додаватися до назви каталогу, розділеного -.

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

Повертає null, якщо не вдалося відкрити каталог. Ви можете використовувати get_open_error(), щоб перевірити помилку, яка сталася.

bool current_is_dir() const 🔗

Повертаємо вашу увагу на те, що поточний елемент, оброблений останнім get_next(), є каталогом (`` і `` та ``. `` вважаються каталогами.

bool dir_exists(path: String) 🔗

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

Примітка: Повернений bool у редакторі та після експорту, коли використовується на шляху в каталозі res://, може відрізнятися. Деякі файли під час експорту перетворюються на формати, специфічні для механізму, потенційно змінюючи структуру каталогів.

bool dir_exists_absolute(path: String) static 🔗

Статична версія dir_exists(). Підтримує лише абсолютні шляхи.

Примітка: Повернений bool у редакторі та після експорту, коли використовується на шляху в каталозі res://, може відрізнятися. Деякі файли під час експорту перетворюються на формати, специфічні для механізму, потенційно змінюючи структуру каталогів.

bool file_exists(path: String) 🔗

Повертає, чи існує цільовий файл. Аргумент може бути відносним до поточного каталогу або абсолютним шляхом.

Для статичного еквівалента використовуйте FileAccess.file_exists().

Примітка: Імпортується багато типів ресурсів (наприклад, текстури чи звукові файли), і їхні вихідні ресурси не будуть включені в експортовану гру, оскільки використовується лише імпортована версія. Перегляньте ResourceLoader.exists() для альтернативного підходу, який враховує перевідображення ресурсів.

String get_current_dir(include_drive: bool = true) const 🔗

Повертає абсолютний шлях до відкритого каталогу (наприклад, res://folder або C:\tmp\folder).

int get_current_drive() 🔗

Повернення в даний час відкритий індекс передачі каталогу. Див. get_drive_name() для перетворення індексу повертається в ім'я диска.

PackedStringArray get_directories() 🔗

Повертає PackedStringArray, що містить імена файлів із вмістом каталогу, за винятком файлів. Масив відсортовано за алфавітом.

Впливають include_hidden і include_navigational.

Примітка: Повернуті каталоги в редакторі та після експорту в каталозі res:// можуть відрізнятися, оскільки деякі файли під час експорту перетворюються на формати, що відповідають системі.

PackedStringArray get_directories_at(path: String) static 🔗

Повертає PackedStringArray, що містить імена файлів із вмістом каталогу, за винятком файлів, за заданим path. Масив відсортовано за алфавітом.

Використовуйте get_directories(), якщо ви хочете більше контролювати те, що буде включено.

Примітка: Повернуті каталоги в редакторі та після експорту в каталозі res:// можуть відрізнятися, оскільки деякі файли під час експорту перетворюються на формати, що відповідають системі.

int get_drive_count() static 🔗

У Windows повертає кількість дисків (розділів), підключених до поточної файлової системи.

У macOS та Android повертає кількість підключених томів.

У Linux повертає кількість підключених томів та закладок GTK 3.

На інших платформах метод повертає 0.

String get_drive_label(idx: int) static 🔗

On Windows, returns the label of the drive (partition) passed as an argument.

On other platforms, or if the requested drive does not exist, returns an empty String.

String get_drive_name(idx: int) static 🔗

On Windows, returns the name of the drive (partition) passed as an argument (e.g. C:).

On macOS, returns the path to the mounted volume passed as an argument.

On Linux, returns the path to the mounted volume or GTK 3 bookmark passed as an argument.

On Android (API level 30+), returns the path to the mounted volume as an argument.

On other platforms, or if the requested drive does not exist, returns an empty String.

PackedStringArray get_files() 🔗

Повертає масив PackedStringArray, що містить імена файлів вмісту каталогів, за винятком каталогів. Масив відсортовано за алфавітом.

Впливає на include_hidden.

Примітка: При використанні на шляху res:// в експортованому проекті повертаються лише ті файли, які фактично включено до PCK на рівні даної теки. На практиці це означає, що оскільки імпортовані ресурси зберігаються у теці верхнього рівня .godot/, повертаються лише шляхи до файлів *.gd і *.import (плюс кілька файлів, таких як project.godot або project.binary та піктограма проекту). В експортованому проекті список повернених файлів також буде відрізнятися залежно від того, чи має значення ProjectSettings.editor/export/convert_text_resources_to_binary true.

PackedStringArray get_files_at(path: String) static 🔗

Повертає PackedStringArray, що містить імена файлів із вмістом каталогу, за винятком каталогів, за заданим path. Масив відсортовано за алфавітом.

Використовуйте get_files(), якщо ви хочете більше контролювати те, що буде включено.

Примітка: Якщо використовується на шляху res:// в експортованому проекті, повертаються лише файли, включені до PCK на заданому рівні папки. На практиці це означає, що оскільки імпортовані ресурси зберігаються в папці .godot/ верхнього рівня, повертаються лише шляхи до файлів .gd і .import (плюс кілька інших файлів, таких як project.godot або project.binary і піктограма проекту). В експортованому проекті список повернутих файлів також буде відрізнятися залежно від ProjectSettings.editor/export/convert_text_resources_to_binary.

String get_filesystem_type() const 🔗

Повертає назву типу файлової системи диска поточного каталогу. Повертаються значення у верхньому регістрі, наприклад, NTFS, FAT32, EXFAT, APFS, EXT4, BTRFS тощо.

Примітка: Цей метод реалізовано в macOS, Linux, Windows та для віртуальної файлової системи PCK.

String get_next() 🔗

Повертає наступний елемент (файл або каталог) у поточному каталозі.

Ім'я файлу або каталогу повертається (і не його повний шлях). Після того, як потік був повністю оброблений, метод повертає порожній String і закриває потік автоматично (тобто list_dir_end() не обов'язково буде в такому випадку).

Error get_open_error() static 🔗

Повертає результат останнього виклику open() у поточному потоці.

int get_space_left() 🔗

Повертає наявний простір на поточному диску каталогу, в байтах. Повертаємо 0, якщо конкретний метод платформи для запиту наявного простору не виходить.

bool is_bundle(path: String) const 🔗

Повертає true, якщо каталог є пакетом macOS.

Примітка: Цей метод реалізовано в macOS.

bool is_case_sensitive(path: String) const 🔗

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

Примітка: Цей метод реалізується на macOS, Linux (для файлових систем EXT4 і F2FS) і Windows. На інших платформах завжди повертається true.

bool is_equivalent(path_a: String, path_b: String) const 🔗

Повертає true, якщо шляхи path_a та path_b ведуть до одного й того ж об'єкта файлової системи. Повертає false в іншому випадку, навіть якщо файли ідентичні побітово (наприклад, ідентичні копії файлу, які не є символічними посиланнями).

bool is_link(path: String) 🔗

Повертає true, якщо файл або каталог є символічним посиланням, з'єднання каталогів, або іншим пунктом репарації.

Примітка: Цей метод реалізується на macOS, Linux та Windows.

Error list_dir_begin() 🔗

Ініціалізує потік, який використовується для переліку всіх файлів і каталогів за допомогою функції get_next(), закриваючи поточний відкритий потік, якщо це необхідно. Після обробки потоку його зазвичай слід закрити за допомогою list_dir_end().

Впливає на include_hidden та include_navigational.

Примітка: Порядок файлів і каталогів, що повертаються цим методом, не є детермінованим і може відрізнятися у різних операційних системах. Якщо вам потрібен список усіх файлів або каталогів, відсортованих за алфавітом, скористайтеся get_files() або get_directories().

void list_dir_end() 🔗

Закриває поточний потік, відкритий за допомогою list_dir_begin() (чи був він повністю оброблений за допомогою get_next(), не має значення).

Error make_dir(path: String) 🔗

Створення каталогу. Привод може бути відносно поточного каталогу або абсолютного шляху. Цільовий каталог повинен бути розміщений в вже існуючому каталозі (для створення повноцінного шляху прямо заразно, див. make_dir_recursive()).

Повертаємо один з кодових констанцій (@GlobalScope.OK на успіх).

Error make_dir_absolute(path: String) static 🔗

Статична версія методу make_dir. Підтримує лише абсолютні шляхи.

Error make_dir_recursive(path: String) 🔗

Створює цільовий каталог і всі необхідні проміжні каталоги в своєму шляху, за допомогою виклику зробити_dir() рекурсивно. Привод може бути відносно поточного каталогу або абсолютного шляху.

Повертаємо один з кодових констанцій (@GlobalScope.OK на успіх).

Error make_dir_recursive_absolute(path: String) static 🔗

Статична версія make_dir_recursive(). Підтримує лише абсолютні шляхи.

DirAccess open(path: String) static 🔗

Створює новий об'єкт DirAccess і відкриває існуючий каталог файлової системи. Шлях path може бути в дереві проєкту (res://folder), каталозі користувача (user://folder) або бути абсолютним шляхом файлової системи користувача (наприклад, /tmp/folder або C:\tmp\folder).

Повертає null при невдачі під час відкриття каталогу. Ви можете використовувати get_open_error() для перевірки помилки, яка сталася.

String read_link(path: String) 🔗

Повертає ціль символічного посилання.

Примітка: Цей метод реалізується на macOS, Linux та Windows.

Error remove(path: String) 🔗

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

Якщо ви не хочете видалити файл/спрямування постійно, скористайтеся OS.move_to_trash().

Повертаємо один з кодових констанцій (@GlobalScope.OK на успіх).

Error remove_absolute(path: String) static 🔗

Статична версія remove(). Підтримує лише абсолютні шляхи.

Error rename(from: String, to: String) 🔗

Перейменування from файл або каталог до to призначення. Обидва аргументи повинні бути шляхами до файлів або каталогів, або відносної або абсолютної. Якщо файл призначення або каталог не існує доступу, він буде перезаписати.

Повертаємо один з кодових констанцій (@GlobalScope.OK на успіх).

Error rename_absolute(from: String, to: String) static 🔗

Статична версія rename(). Підтримує лише абсолютні шляхи.