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。

以下是遍历目录中文件的示例：

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_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://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) 🔗

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

静态版本见 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 上，返回挂载卷的数量。

在 Linux 上，返回挂载卷与 GTK 3 书签的数量。

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

String get_drive_name(idx: int) static 🔗

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

在 macOS 上，返回作为参数传递的挂载卷的路径。

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

在其他平台上，或者当请求的驱动器不存在时，该方法会返回空的 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_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()。仅支持绝对路径。