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

提供管理目錄及其內容的方法。

說明

This class is used to manage directories and their content, even outside of the project folder.

DirAccess can't be instantiated directly. Instead it is created with a static method that takes a path for which it will be opened.

Most of the methods have a static alternative that can be used without creating a DirAccess. Static methods only support absolute paths (including res:// and user://).

# Standard
var dir = DirAccess.open("user://levels")
dir.make_dir("world1")
# Static
DirAccess.make_dir_absolute("user://levels/world1")

Note: Accessing project ("res://") directories once exported may behave unexpectedly as some files are converted to engine-specific formats and their original source files may not be present in the expected PCK package. Because of this, to access resources in an exported project, it is recommended to use ResourceLoader instead of FileAccess.

Here is an example on how to iterate through the files of a directory:

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())
            {
                GD.Print($"Found directory: {fileName}");
            }
            else
            {
                GD.Print($"Found file: {fileName}");
            }
            fileName = dir.GetNext();
        }
    }
    else
    {
        GD.Print("An error occurred when trying to access the path.");
    }
}

Keep in mind that file names may change or be remapped after export. If you want to see the actual resource file list as it appears in the editor, use ResourceLoader.list_directory() instead.

教學

檔案系統

屬性

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_label(idx: int) 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) 🔗

Changes the currently opened directory to the one passed as an argument. The argument can be relative to the current directory (e.g. newdir or ../newdir), or an absolute path (e.g. /tmp/newdir or res://somedir/newdir).

Returns one of the Error code constants (@GlobalScope.OK on success).

Note: The new directory must be within the same scope, e.g. when you had opened a directory inside res://, you can't change it to user:// directory. If you need to open a directory in another access scope, use open() to create a new instance instead.

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

Creates symbolic link between files or folders.

Note: On Windows, this method works only if the application is running with elevated privileges or Developer Mode is enabled.

Note: This method is implemented on macOS, Linux, and Windows.

DirAccess create_temp(prefix: String = "", keep: bool = false) static 🔗

Creates a temporary directory. This directory will be freed when the returned DirAccess is freed.

If prefix is not empty, it will be prefixed to the directory name, separated by a -.

If keep is true, the directory is not deleted when the returned DirAccess is freed.

Returns null if opening the directory failed. You can use get_open_error() to check the error that occurred.

bool current_is_dir() const 🔗

返回上一次 get_next() 呼叫處理的目前專案是否為目錄（. 和 . 屬於目錄）。

bool dir_exists(path: String) 🔗

Returns whether the target directory exists. The argument can be relative to the current directory, or an absolute path.

Note: The returned bool in the editor and after exporting when used on a path in the res:// directory may be different. Some files are converted to engine-specific formats when exported, potentially changing the directory structure.

bool dir_exists_absolute(path: String) static 🔗

Static version of dir_exists(). Supports only absolute paths.

Note: The returned bool in the editor and after exporting when used on a path in the res:// directory may be different. Some files are converted to engine-specific formats when exported, potentially changing the directory structure.

bool file_exists(path: String) 🔗

Returns whether the target file exists. The argument can be relative to the current directory, or an absolute path.

For a static equivalent, use FileAccess.file_exists().

Note: Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. See ResourceLoader.exists() for an alternative approach that takes resource remapping into account.

String get_current_dir(include_drive: bool = true) const 🔗

返回目前打開目錄的絕對路徑（例如 res://資料夾 或 C:\tmp\資料夾）。

int get_current_drive() 🔗

返回目前打開目錄的驅動器索引。要將返回的索引轉換為驅動器名稱，請參閱 get_drive_name()。

PackedStringArray get_directories() 🔗

Returns a PackedStringArray containing filenames of the directory contents, excluding files. The array is sorted alphabetically.

Affected by include_hidden and include_navigational.

Note: The returned directories in the editor and after exporting in the res:// directory may differ as some files are converted to engine-specific formats when exported.

PackedStringArray get_directories_at(path: String) static 🔗

Returns a PackedStringArray containing filenames of the directory contents, excluding files, at the given path. The array is sorted alphabetically.

Use get_directories() if you want more control of what gets included.

Note: The returned directories in the editor and after exporting in the res:// directory may differ as some files are converted to engine-specific formats when exported.

int get_drive_count() static 🔗

On Windows, returns the number of drives (partitions) mounted on the current filesystem.

On macOS and Android, returns the number of mounted volumes.

On Linux, returns the number of mounted volumes and GTK 3 bookmarks.

On other platforms, the method returns 0.

String get_drive_label(idx: int) static 🔗

On Windows, returns the label of the drive (partition) passed as an argument.

On other platforms, or if the requested drive does not exist, returns an empty String.

String get_drive_name(idx: int) static 🔗

On Windows, returns the name of the drive (partition) passed as an argument (e.g. C:).

On macOS, returns the path to the mounted volume passed as an argument.

On Linux, returns the path to the mounted volume or GTK 3 bookmark passed as an argument.

On Android (API level 30+), returns the path to the mounted volume as an argument.

On other platforms, or if the requested drive does not exist, returns an empty 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 🔗

Returns a PackedStringArray containing filenames of the directory contents, excluding directories, at the given path. The array is sorted alphabetically.

Use get_files() if you want more control of what gets included.

Note: When used on a res:// path in an exported project, only the files included in the PCK at the given folder level are returned. In practice, this means that since imported resources are stored in a top-level .godot/ folder, only paths to .gd and .import files are returned (plus a few other files, such as project.godot or project.binary and the project icon). In an exported project, the list of returned files will also vary depending on ProjectSettings.editor/export/convert_text_resources_to_binary.

String get_filesystem_type() const 🔗

Returns file system type name of the current directory's disk. Returned values are uppercase strings like NTFS, FAT32, EXFAT, APFS, EXT4, BTRFS, and so on.

Note: This method is implemented on macOS, Linux, Windows and for PCK virtual file system.

String get_next() 🔗

返回目前的目錄中的下一個元素（檔或目錄）。

返回的是檔或目錄的名稱（不是完整路徑）。完全處理完流之後，該方法會返回空 String 並自動將流關閉（即此時不必再呼叫 list_dir_end()）。

Error get_open_error() static 🔗

返回目前執行緒中最後一次 open() 呼叫的結果。

int get_space_left() 🔗

返回目前的目錄所在磁片的可用空間，單位為位元組。如果該平臺查詢可用空間的方法失敗，則返回 0。

bool is_bundle(path: String) const 🔗

Returns true if the directory is a macOS bundle.

Note: This method is implemented on macOS.

bool is_case_sensitive(path: String) const 🔗

Returns true if the file system or directory use case sensitive file names.

Note: This method is implemented on macOS, Linux (for EXT4 and F2FS filesystems only) and Windows. On other platforms, it always returns true.

bool is_equivalent(path_a: String, path_b: String) const 🔗

Returns true if paths path_a and path_b resolve to the same file system object. Returns false otherwise, even if the files are bit-for-bit identical (e.g., identical copies of the file that are not symbolic links).

bool is_link(path: String) 🔗

Returns true if the file or directory is a symbolic link, directory junction, or other reparse point.

Note: This method is implemented on macOS, Linux, and 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) 🔗

Returns target of the symbolic link.

Note: This method is implemented on macOS, Linux, and 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()。僅支援絕對路徑。