DirAccess

继承： RefCounted < Object

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

描述

这个类可以用来管理目录及其内容，不限于项目文件夹。

DirAccess 无法直接实例化。请使用接受要打开的路径的静态方法创建。

大多数方法都有静态备选项，无需创建 DirAccess 即可使用。静态方法仅支持绝对路径（包含 res:// 和 user://）。

# 标准
var dir = DirAccess.open("user://levels")
dir.make_dir("world1")
# 静态
DirAccess.make_dir_absolute("user://levels/world1")

注意：很多资源类型是经过导入的（例如纹理和声音文件），因为在游戏中只会用到导入后的版本，所以导出后的游戏中不包含对应的源资产。请使用 ResourceLoader 访问导入的资源。

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

GDScriptC#

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("尝试访问路径时出错。");
    }
}

教程

• 文件系统

属性

方法

属性说明

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 上实现。

bool current_is_dir() const 🔗

返回上一次 get_next 调用处理的当前项目是否为目录（. 和 . 属于目录）。

bool dir_exists(path: String) 🔗

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

bool dir_exists_absolute(path: String) static 🔗

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

bool file_exists(path: String) 🔗

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

对于静态等效项，请使用 FileAccess.file_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 的影响。

PackedStringArray get_directories_at(path: String) static 🔗

返回位于给定路径 path 的目录内容的文件名 PackedStringArray，不含文件。该数组按字母排序。

如果你想要对包括的内容有更多的控制，请使用 get_directories。

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。

String get_next() 🔗

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

返回的是文件或目录的名称（不是完整路径）。完全处理完流之后，该方法会返回空 String 并自动将流关闭（即此时不必再调用 list_dir_end）。

Error get_open_error() static 🔗

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

int get_space_left() 🔗

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

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。仅支持绝对路径。