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.

Вот пример того, как перебирать файлы каталога:

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("Found directory: " + file_name)
            else:
                print("Found file: " + file_name)
            file_name = dir.get_next()
    else:
        print("An error occurred when trying to access the path.")

public void DirContents(string path)
{
    using var dir = DirAccess.Open(path);
    if (dir != null)
    {
        dir.ListDirBegin();
        string fileName = dir.GetNext();
        while (fileName != "")
        {
            if (dir.CurrentIsDir())
            {
                GD.Print($"Found directory: {fileName}");
            }
            else
            {
                GD.Print($"Found file: {fileName}");
            }
            fileName = dir.GetNext();
        }
    }
    else
    {
        GD.Print("An error occurred when trying to access the path.");
    }
}

Имейте в виду, что имена файлов могут измениться или быть переназначены после экспорта. Если вы хотите увидеть фактический список файлов ресурсов, как он отображается в редакторе, используйте вместо этого 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_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).

Возвращает одну из констант кода Error (@GlobalScope.OK при успешном выполнении).

Примечание: Новый каталог должен находиться в той же области, например, если вы открыли каталог внутри res://, вы не можете изменить его на каталог user://. Если вам нужно открыть каталог в другой области доступа, используйте open() для создания нового экземпляра.

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

Копирует файл from в место назначения to. Оба аргумента должны быть путями к файлам, относительными или абсолютными. Если файл назначения существует и не защищен от доступа, он будет перезаписан.

Если chmod_flags отличается от -1, разрешения Unix для пути назначения будут установлены на указанное значение, если оно доступно в текущей операционной системе.

Возвращает одну из констант кода Error (@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_name(idx: int) static 🔗

В Windows возвращает имя диска (раздела), переданное в качестве аргумента (например, C:).

В macOS возвращает путь к смонтированному тому, переданному в качестве аргумента.

В Linux возвращает путь к смонтированному тому или закладке GTK 3, переданной в качестве аргумента.

В Android (уровень API 30+) возвращает путь к смонтированному тому в качестве аргумента.

На других платформах или если запрошенный диск не существует, метод возвращает пустую строку.

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

Возвращает одну из констант кода Error (@GlobalScope.OK при успешном выполнении).

Error make_dir_absolute(path: String) static 🔗

Статическая версия make_dir(). Поддерживает только абсолютные пути.

Error make_dir_recursive(path: String) 🔗

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

Возвращает одну из констант кода Error (@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().

Возвращает одну из констант кода Error (@GlobalScope.OK при успешном выполнении).

Error remove_absolute(path: String) static 🔗

Статическая версия remove(). Поддерживает только абсолютные пути.

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

Переименовывает (перемещает) файл или каталог from в место назначения to. Оба аргумента должны быть путями к файлам или каталогам, относительными или абсолютными. Если файл или каталог назначения существует и не защищен от доступа, он будет перезаписан.

Возвращает одну из констант кода Error (@GlobalScope.OK при успешном выполнении).

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

Статическая версия rename(). Поддерживает только абсолютные пути.