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("发现目录：" + file_name)
            else:
                print("发现文件" + file_name)
            file_name = dir.get_next()
    else:
        print("尝试访问路径时出错。")

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($"发现目录：{fileName}");
            }
            else
            {
                GD.Print($"发现文件：{fileName}");
            }
            fileName = dir.GetNext();
        }
    }
    else
    {
        GD.Print("尝试访问路径时出错。");
    }
}

请牢记，导出后文件名可能发生变化和重映射。如果想要看到和编辑器中一致的实际资源文件列表，请改用 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) 🔗

创建文件或文件夹的符号链接。

注意：在 Window 上，使用提升权限运行程序或启用“开发者模式”时该方法才能正常工作。

注意：该方法仅在 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 dir_exists_absolute(path: String) static 🔗

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

注意：使用 res:// 目录下的路径时，在编辑器中返回的 bool 与导出后的返回值可能不同。导出时会将部分文件转换为引擎特有的格式，可能导致目录结构的改变。

bool file_exists(path: String) 🔗

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

静态版本见 FileAccess.file_exists()。

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

String get_current_dir(include_drive: bool = true) const 🔗

返回当前打开目录的绝对路径（例如 res://文件夹 或 C:\tmp\文件夹）。

int get_current_drive() 🔗

返回当前打开目录的驱动器索引。要将返回的索引转换为驱动器名称，请参阅 get_drive_name()。

PackedStringArray get_directories() 🔗

返回该目录内容的文件名 PackedStringArray，不含文件。该数组按字母顺序排序。

受 include_hidden 和 include_navigational 的影响。

注意：对于 res:// 下的目录，在编辑器中所返回的目录和导出后所返回的目录可能不同，因为导出时可能将部分文件转换为引擎特有的格式。

PackedStringArray get_directories_at(path: String) static 🔗

返回 path 所指向目录内容的文件名 PackedStringArray，不含文件。该数组按字母顺序排序。

如果需要对包含内容做进一步控制，请使用 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+）上，返回作为参数的挂载卷的路径。

在其他平台上，或者当请求的驱动器不存在时，该方法会返回空的 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 🔗

返回 path 所指向目录内容的文件名 PackedStringArray，不含目录。该数组按字母排序。

如果需要对包含内容做进一步控制，请使用 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 🔗

如果该目录为 macOS 捆绑包，则返回 true。

注意：该方法在 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 🔗

如果路径 path_a 和路径 path_b 解析为同一个文件系统对象则返回 true。否则返回 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()。仅支持绝对路径。