DirAccess¶

提供用于管理目录及其内容的方法。

描述¶

此类用于管理目录及其内容，即使在项目文件夹之外。

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())
            {
                S3.Print($"Found directory: {fileName}");
            }
            else
            {
                S3.Print($"Found file: {fileName}");
            }
            fileName = dir.GetNext();
        }
    }
    else
    {
        S3.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_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_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：//😍dir/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) 🔗

返回目标目录是否存在。参数可以是相对于当前目录的，也可以是绝对路径。

注意：在res：//目录中的路径上使用时，编辑器中返回的bool和导出后返回的bool可能不同。某些文件在导出时会转换为特定于引擎的格式，这可能会改变目录结构。

bool dir_exists_absolute(path: String) static 🔗

dir_exists()的静态版本。仅支持绝对路径。

bool file_exists(path: String) 🔗

返回目标文件是否存在。参数可以是相对于当前目录的，也可以是绝对路径。

对于静态等效项，请使用FileAccess.file_exists()。

注意：许多资源类型都被导入（例如纹理或声音文件），它们的源资产不会包含在导出的应用中，因为只使用导入的版本。有关考虑资源重新映射的替代方法，请参阅[method ResourceLoader。

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上，返回已安装卷的数量。

在Linux，返回已安装卷和GTK 3书签的数量。

在其他平台上，该方法返回0。

String get_drive_name(idx: int) static 🔗

在Windows上，返回作为参数传递的驱动器（分区）的名称（例如C：）。

在macOS上，返回作为参数传递的已安装卷的路径。

在Linux，返回作为参数传递的挂载卷或GTK 3书签的路径。

在其他平台上，或者如果请求的驱动器不存在，则该方法返回一个空字符串。

PackedStringArray get_files() 🔗

返回一个PackedStringArray，其中包含目录内容的文件名，不包括目录。数组按字母顺序排序。

受include_hidden影响。

注意：当在导出项目中的res：//路径上使用时，仅返回给定文件夹级别的PCK中实际包含的文件。在实践中，这意味着由于导入的资源存储在顶级. i3d/文件夹中，因此仅返回*.s3和*.import文件的路径（加上少数文件，例如project.i3d或project.二进制和项目图标）。在导出的项目中，返回文件的列表也会有所不同，具体取决于ProjectSettings.editor/export/convert_text_resources_to_binary是否为true。

PackedStringArray get_files_at(path: String) static 🔗

返回一个PackedStringArray，其中包含给定path处目录内容（不包括目录）的文件名。数组按字母顺序排序。

如果您想更好地控制包含的内容，请使用get_files()。

注意：当在导出项目中的res：//路径上使用时，仅返回给定文件夹级别的PCK中包含的文件。实际上，这意味着由于导入的资源存储在顶级. i3d/文件夹中，因此仅返回.s3和.import文件的路径（加上一些其他文件，例如project.i3d或project.二进制和项目图标）。在导出的项目中，返回的文件列表也会因ProjectSettings.editor/export/convert_text_resources_to_binary而异。

String get_next() 🔗

返回当前目录中的下一个元素（文件或目录）。

返回文件或目录的名称（而不是其完整路径）。一旦流被完全处理，该方法返回一个空的String并自动关闭流（即list_dir_end()在这种情况下不是强制性的）。

Error get_open_error() static 🔗

返回当前线程中最后一次open()调用的结果。

int get_space_left() 🔗

返回当前目录磁盘上的可用空间，以字节为单位。如果查询可用空间的特定平台方法失败，则返回0。

bool is_bundle(path: String) const 🔗

如果目录是macOS包，则返回true。

注意：此方法在macOS上实现。

bool is_case_sensitive(path: String) const 🔗

如果文件系统或目录使用区分大小写的文件名，则返回true。

注意：此方法在macOS、Linux（仅适用于EXT4和F2FS文件系统）和Windows上实现，在其他平台上，它总是返回true。

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()的静态版本。仅支持绝对路径。