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")

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

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

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
bool	include_navigational

方法¶

Error	change_dir ( String to_dir )
Error	copy ( String from, String to, int chmod_flags=-1 )
Error	copy_absolute ( String from, String to, int chmod_flags=-1 ) static
bool	current_is_dir ( ) const
bool	dir_exists ( String path )
bool	dir_exists_absolute ( String path ) static
bool	file_exists ( String path )
String	get_current_dir ( bool include_drive=true ) const
int	get_current_drive ( )
PackedStringArray	get_directories ( )
PackedStringArray	get_directories_at ( String path ) static
int	get_drive_count ( ) static
String	get_drive_name ( int idx ) static
PackedStringArray	get_files ( )
PackedStringArray	get_files_at ( String path ) static
String	get_next ( )
Error	get_open_error ( ) static
int	get_space_left ( )
bool	is_case_sensitive ( String path ) const
Error	list_dir_begin ( )
void	list_dir_end ( )
Error	make_dir ( String path )
Error	make_dir_absolute ( String path ) static
Error	make_dir_recursive ( String path )
Error	make_dir_recursive_absolute ( String path ) static
DirAccess	open ( String path ) static
Error	remove ( String path )
Error	remove_absolute ( String path ) static
Error	rename ( String from, String to )
Error	rename_absolute ( String from, String to ) static

属性说明¶

bool include_hidden

void set_include_hidden ( bool value )
bool get_include_hidden ( )

如果为 true，则在导航目录时包含隐藏文件。

影响 list_dir_begin、get_directories、get_files。

bool include_navigational

void set_include_navigational ( bool value )
bool get_include_navigational ( )

如果为 true，则在导航目录时包含 . 和 ..。

影响 list_dir_begin 和 get_directories。

方法说明¶

Error change_dir ( String to_dir )

将当前打开的目录改为作为参数传递的目录。该参数可以是相对于当前目录的（例如 newdir 或 ../newdir），也可以是绝对路径（例如 /tmp/newdir 或 res://somedir/newdir）。

返回 Error 错误码常量之一（成功时为 @GlobalScope.OK）。

注意：新目录必须在相同范围内，例如当在 res:// 中打开目录时，无法将其更改为 user:// 目录。如果需要在另一个访问范围中打开目录，请使用 open 创建一个新实例。

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

将 from 文件复制到 to 目标位置。两个参数都应该是文件的路径，可以是相对路径，也可以是绝对路径。如果目标文件存在并且没有访问保护，则它将被覆盖。

如果 chmod_flags 不同于 -1，且如果在当前操作系统上可用，目标路径的 Unix 权限将设置为提供的值。

返回 Error 错误码常量之一（成功时为 @GlobalScope.OK）。

Error copy_absolute ( String from, String to, int chmod_flags=-1 ) static

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

bool current_is_dir ( ) const

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

bool dir_exists ( String path )

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

bool dir_exists_absolute ( String path ) static

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

bool file_exists ( String path )

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

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

String get_current_dir ( bool include_drive=true ) const

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

int get_current_drive ( )

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

PackedStringArray get_directories ( )

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

受 include_hidden 和 include_navigational 的影响。

PackedStringArray get_directories_at ( String path ) static

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

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

int get_drive_count ( ) static

在 Windows 上，返回挂载在当前文件系统上的驱动器（分区）数量。

在 macOS 上，返回挂载卷的数量。

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

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

String get_drive_name ( int idx ) 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 ( String path ) 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 ( String path ) const

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

注意：该方法在 macOS、Linux（仅对于 EXT4 和 F2FS 文件系统）和 Windows 上实现。在其他平台上，它始终返回 true。

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 ( String path )

创建目录。参数可以相对于当前目录，也可以是绝对路径。目标目录应该位于已经存在的目录中（递归创建完整的路径请参阅 make_dir_recursive）。

返回 Error 错误码常量（成功时为 @GlobalScope.OK）。

Error make_dir_absolute ( String path ) static

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

Error make_dir_recursive ( String path )

递归调用 make_dir 方法，创建目标目录及其路径中所有必要的中间目录。参数可以相对于当前目录，也可以是绝对路径。

返回 Error 错误码常量（成功时为 @GlobalScope.OK）。

Error make_dir_recursive_absolute ( String path ) static

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

DirAccess open ( String path ) static

新建 DirAccess 对象并打开文件系统中的某个现存目录。path 参数可以是在项目树中（res://folder）、用户目录中（user://folder），也可以是用户文件系统的绝对路径（例如 /tmp/folder 或 C:\tmp\folder）。

如果打开目录失败，则返回 null。你可以使用 get_open_error 来查看发生的错误。

Error remove ( String path )

将目标文件或空目录永久删除。参数可以相对于当前目录，也可以是绝对路径。如果目标目录非空，则操作失败。

如果你不想永久删除该文件/目录，请改用 OS.move_to_trash。

返回 Error 错误码常量（成功时为 @GlobalScope.OK）。

Error remove_absolute ( String path ) static

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

Error rename ( String from, String to )

将 from 文件或目录重命名为（移动至）to 目标。两个参数都应该是文件或目录的路径，可以是相对路径也可以是绝对路径。如果目标文件或目录已存在，并且没有写保护，则会被覆盖。

返回 Error 错误码常量（成功时为 @GlobalScope.OK）。

Error rename_absolute ( String from, String to ) static

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