FileAccess¶
继承： RefCounted < Object
提供文件读取和写入操作的方法。
描述¶
此类可用于将数据永久存储在用户设备的文件系统中并从中读取。这对于存储应用保存数据或用户配置文件很有用。
这是有关如何写入和读取文件的示例：
func save_to_file(content):
var file = FileAccess.open("user://save_game.dat", FileAccess.WRITE)
file.store_string(content)
func load_from_file():
var file = FileAccess.open("user://save_game.dat", FileAccess.READ)
var content = file.get_as_text()
return content
public void SaveToFile(string content)
{
using var file = FileAccess.Open("user://save_game.dat", FileAccess.ModeFlags.Write);
file.StoreString(content);
}
public string LoadFromFile()
{
using var file = FileAccess.Open("user://save_game.dat", FileAccess.ModeFlags.Read);
string content = file.GetAsText();
return content;
}
在上述示例中，文件将按照Data paths文档中指定的路径保存在用户数据文件夹中。当文件超出作用域或被赋值为null时，FileAccess将被关闭。close()可用于在此之前显式关闭它。在C#中，必须手动释放引用，可以使用using语句或直接调用Dispose方法来实现。
注意：一旦导出项目资源，建议使用ResourceLoader而不是FileAccess，因为有些文件被转换为引擎特定的格式，其原始源文件可能不在导出的PCK包中。如果使用FileAccess，请确保文件被包含在导出中，方法是在导入面板中将其导入模式更改为保留文件（原样导出），或者对于没有此选项的文件，在导出对话框中更改非资源导出过滤器以包含文件的扩展名（例如*.txt）。
注意：只有在进程“正常”退出时（例如通过点击窗口管理器的关闭按钮或按Alt + F4），文件才会自动关闭。如果在项目运行时按F8停止项目执行，则文件不会关闭，因为应用进程将被终止。您可以通过定期调用flush()来解决此问题。
属性¶
方法¶
枚举¶
enum ModeFlags: 🔗
ModeFlags READ = 1
打开文件进行读取操作。光标位于文件的开头。
ModeFlags WRITE = 2
打开文件进行写入操作。如果文件不存在，则创建该文件，如果存在，则截断该文件。
注意：创建文件时，它必须位于已经存在的目录中。要递归地为文件路径创建目录，请参阅DirAccess.make_dir_recursive()。
ModeFlags READ_WRITE = 3
打开文件进行读写操作。不截断文件。光标位于文件的开头。
ModeFlags WRITE_READ = 7
打开文件进行读写操作。如果文件不存在，则创建该文件，如果存在，则截断该文件。光标位于文件的开头。
注意：创建文件时，它必须位于已经存在的目录中。要递归地为文件路径创建目录，请参阅DirAccess.make_dir_recursive()。
enum CompressionMode: 🔗
CompressionMode COMPRESSION_FASTLZ = 0
使用FastLZ压缩方法。
CompressionMode COMPRESSION_DEFLATE = 1
使用DEFLATE压缩方法。
CompressionMode COMPRESSION_ZSTD = 2
使用ZStandard压缩方法。
CompressionMode COMPRESSION_GZIP = 3
使用gzip压缩方法。
CompressionMode COMPRESSION_BROTLI = 4
使用brotli压缩方法（仅支持解压缩）。
flags UnixPermissionFlags: 🔗
UnixPermissionFlags UNIX_READ_OWNER = 256
读取所有者位。
UnixPermissionFlags UNIX_WRITE_OWNER = 128
为所有者位写入。
UnixPermissionFlags UNIX_EXECUTE_OWNER = 64
为所有者位执行。
UnixPermissionFlags UNIX_READ_GROUP = 32
读取组位。
UnixPermissionFlags UNIX_WRITE_GROUP = 16
写入组位。
UnixPermissionFlags UNIX_EXECUTE_GROUP = 8
执行组位。
UnixPermissionFlags UNIX_READ_OTHER = 4
阅读其他位。
UnixPermissionFlags UNIX_WRITE_OTHER = 2
写其他位。
UnixPermissionFlags UNIX_EXECUTE_OTHER = 1
执行其他位。
UnixPermissionFlags UNIX_SET_USER_ID = 2048
在执行位上设置用户ID。
UnixPermissionFlags UNIX_SET_GROUP_ID = 1024
在执行位上设置组id。
UnixPermissionFlags UNIX_RESTRICTED_DELETE = 512
限制删除（粘性）位。
属性说明¶
如果true，则使用big-endianendianness读取文件。如果false，则使用little-endian endianness读取文件。如果有疑问，请将其留给false，因为大多数文件都是使用little-endian endianness编写的。
注意：big_endian只是关于文件格式，而不是CPU类型。CPU顺序不会影响写入文件的默认顺序。
注意：每当您打开文件时，这总是重置为false。因此，您必须在打开文件之后设置big_endian，而不是之前。
方法说明¶
void close() 🔗
关闭当前打开的文件并阻止后续的读/写操作。使用flush()将数据持久化到磁盘而不关闭文件。
注意：FileAccess将在释放时自动关闭，当它超出范围或被分配null时会发生这种情况。在C#中，引用必须在我们使用它之后进行处理，这可以使用使用语句或直接调用Dispose方法来完成。
FileAccess create_temp(mode_flags: int, prefix: String = "", extension: String = "", keep: bool = false) static 🔗
创建一个临时文件。当返回的FileAccess被释放时，该文件将被释放。
如果prefix不为空，它将以文件名为前缀，用-分隔。
如果extension不为空，它将附加到临时文件名中。
如果keep为true，则释放返回的FileAccess时不会删除文件。
如果打开文件失败，则返回null。您可以使用get_open_error()检查发生的错误。
如果文件指针已读取到文件末尾，则返回true。
注意：eof_reached（）==false不能用于检查是否有更多可用数据。要在有更多可用数据时循环，请使用：
while file.get_position() < file.get_length():
# 读取数据
while (file.GetPosition() < file.GetLength())
{
// 读取数据
}
bool file_exists(path: String) static 🔗
如果文件存在于给定路径中，则返回true。
注意：许多资源类型都被导入（例如纹理或声音文件），它们的源资产不会包含在导出的应用中，因为只使用导入的版本。有关考虑资源重新映射的替代方法，请参阅ResourceLoader.exists()。
对于非静态的相对等效项，请使用DirAccess.file_exists()。
void flush() 🔗
将文件的缓冲区写入磁盘。当文件关闭时，会自动执行刷新。这意味着您在关闭文件之前不需要手动调用flush()。尽管如此，即使项目崩溃而不是正常关闭，也可以使用调用flush()来确保数据安全。
注意：仅在实际需要时调用flush()。否则，由于不断的磁盘写入，它会降低性能。
以整数形式返回文件中接下来的8位。有关可以以这种方式存储和检索哪些值的详细信息，请参见store_8()。
以整数形式返回文件中接下来的16位。有关可以通过这种方式存储和检索哪些值的详细信息，请参见store_16()。
以整数形式返回文件中接下来的32位。有关可以通过这种方式存储和检索哪些值的详细信息，请参见store_32()。
以整数形式返回文件中接下来的64位。有关可以通过这种方式存储和检索哪些值的详细信息，请参见store_64()。
String get_as_text(skip_cr: bool = false) const 🔗
将整个文件以String形式返回。文本被视为UTF-8编码。
如果skip_cr为true，则在解析UTF-8时将忽略回车符（\r，CR），因此只有换行符（\n，LF）代表新行（Unix约定）。
PackedByteArray get_buffer(length: int) const 🔗
以PackedByteArray的形式返回文件的下一个length字节。
PackedStringArray get_csv_line(delim: String = ",") const 🔗
以CSV（逗号分隔值）格式返回文件的下一个值。可以使用不同的分隔符delim来替代默认的","（逗号）。此分隔符必须为一个字符长度，不能是双引号。文本被解释为UTF-8编码。如果文本值包含分隔符字符，则必须用双引号括号括起来。文本值中的双引号可以通过重复出现来转义。
例如，以下CSV行是有效的，并将被正确解析为两个字符串：
Alice,"Hello, Bob!"
Bob,Alice! What a surprise!
Alice,"I thought you'd reply with ""Hello, world""."
请注意，第二行可以省略引号，因为它不包含分隔符。然而，它完全可以使用引号，只是为了演示而没有使用。第三行必须使用""来表示需要解释为引号的每个引号，而不是文本值的结尾。
从文件中返回接下来的64位作为浮点数。
返回尝试执行操作时发生的最后一个错误。与Error中的ERR_FILE_*常量进行比较。
PackedByteArray get_file_as_bytes(path: String) static 🔗
将整个path文件内容作为PackedByteArray返回，无需任何解码。
如果打开文件时发生错误，则返回一个空的PackedByteArray。您可以使用get_open_error()检查发生的错误。
String get_file_as_string(path: String) static 🔗
以String形式返回整个path文件内容。文本被解释为UTF-8编码。
如果打开文件时发生错误，则返回空String。您可以使用get_open_error()检查发生的错误。
从文件中返回接下来的32位作为浮点数。
将文件中接下来的16位作为半精度浮点数返回。
如果设置了文件隐藏属性，则返回true。
注意：此方法在iOS、BSD、macOS和Windows上实现。
以字节为单位返回文件的大小。对于管道，返回可从管道读取的字节数。
以String形式返回文件的下一行。返回的字符串不包含换行符（\n）或回车符（\r）字符，但包含任何其他开头或结尾空白字符。
文本被视为UTF-8编码。
String get_md5(path: String) static 🔗
返回一个MD5字符串，表示给定路径处的文件，或在失败时返回一个空的String。
int get_modified_time(file: String) static 🔗
返回上次以Unix时间戳格式修改file的时间，或错误时返回0。此Unix时间戳可以使用Time单例转换为另一种格式。
Error get_open_error() static 🔗
返回当前线程中最后一次open()调用的结果。
从文件中返回以Pascal格式保存的String。
文本被解释为UTF-8编码。
以String形式返回当前打开文件的路径。
String get_path_absolute() const 🔗
以String形式返回当前打开文件的绝对路径。
返回文件光标的位置。
bool get_read_only_attribute(file: String) static 🔗
如果设置了file只读属性，则返回true。
注意：此方法在iOS、BSD、macOS和Windows上实现。
将文件中的下一位作为浮点数返回。
String get_sha256(path: String) static 🔗
返回表示给定路径处文件的SHA-256String或失败时返回空String。
BitField[UnixPermissionFlags] get_unix_permissions(file: String) static 🔗
返回文件UNIX权限。
注意：此方法在iOS、Linux/BSD和macOS上实现。
Variant get_var(allow_objects: bool = false) const 🔗
返回文件中的下一个Variant值。如果allow_objects为true，则允许解码对象。
在内部，这使用与@GlobalScope.bytes_to_var()方法相同的解码机制。
警告：反序列化对象可能包含被执行的代码。如果序列化对象来自不受信任的来源，请不要使用此选项以避免潜在的安全威胁，例如远程代码执行。
如果文件当前打开，则返回true。
FileAccess open(path: String, flags: ModeFlags) static 🔗
创建一个新的FileAccess对象并打开文件以进行写入或读取，具体取决于标志。
如果打开文件失败，则返回null。您可以使用get_open_error()检查发生的错误。
FileAccess open_compressed(path: String, mode_flags: ModeFlags, compression_mode: CompressionMode = 0) static 🔗
创建一个新的FileAccess对象并打开一个压缩文件以进行读取或写入。
注意：open_compressed()只能读取由i3D保存的文件，不能读取第三方压缩格式。有关解决方法，请参阅GitHub问题#28999。
如果打开文件失败，则返回null。您可以使用get_open_error()检查发生的错误。
FileAccess open_encrypted(path: String, mode_flags: ModeFlags, key: PackedByteArray, iv: PackedByteArray = PackedByteArray()) static 🔗
创建一个新的FileAccess对象并以写入或读取模式打开一个加密文件。您需要传递一个二进制密钥来加密/解密它。
注意：提供的密钥必须为32字节长。
如果打开文件失败，则返回null。您可以使用get_open_error()检查发生的错误。
FileAccess open_encrypted_with_pass(path: String, mode_flags: ModeFlags, pass: String) static 🔗
创建一个新的FileAccess对象并以写入或读取模式打开一个加密文件。您需要传递密码才能加密/解密它。
如果打开文件失败，则返回null。您可以使用get_open_error()检查发生的错误。
将文件调整为指定的长度。文件必须以允许写入的模式打开。如果文件被扩展，则附加NUL字符。如果文件被截断，则从结束文件到文件原始长度的所有数据都将丢失。
将文件读/写光标更改到指定位置（以文件开头的字节为单位）。
void seek_end(position: int = 0) 🔗
将文件读/写光标更改到指定位置（以文件末尾的字节为单位）。
注意：这是一个偏移量，因此您应该使用负数，否则光标将位于文件末尾。
设置文件隐藏属性。
注意：此方法在iOS、BSD、macOS和Windows上实现。
Error set_read_only_attribute(file: String, ro: bool) static 🔗
设置文件只读属性。
注意：此方法在iOS、BSD、macOS和Windows上实现。
Error set_unix_permissions(file: String, permissions: BitField[UnixPermissionFlags]) static 🔗
设置文件UNIX权限。
注意：此方法在iOS、Linux/BSD和macOS上实现。
将整数存储为文件中的8位。
注意：value应该位于区间[0,255]中。任何其他值都会溢出并环绕。
注意：如果发生错误，则文件位置指示符的结果值不确定。
要存储有符号整数，请使用store_64()，或手动转换它（有关示例，请参阅store_16()）。
将一个整数以16位的形式存储在文件中.
注意： value 应在[0, 2^16 - 1]范围内。任何其他值都将溢出并循环使用。
注意：如果发生错误，则文件位置指示器的结果值是不确定的。
要存储有符号整数，请使用store_64()或存储来自[-2^15, 2^15 - 1]范围的有符号整数（即保留一个位用于符号），并在读取时手动计算其符号。例如：
const MAX_15B = 1 << 15
const MAX_16B = 1 << 16
func unsigned16_to_signed(unsigned):
return (unsigned + MAX_15B) % MAX_16B - MAX_15B
func _ready():
var f = FileAccess.open("user://file.dat", FileAccess.WRITE_READ)
f.store_16(-42) # 环绕存储 65494 (2^16 - 42).
f.store_16(121) # 在有效范围内，容量为 121 。
f.seek(0) # 回到起始位置，重新读取存储的值。
var read1 = f.get_16() # 65494
var read2 = f.get_16() # 121
var converted1 = unsigned16_to_signed(read1) # -42
var converted2 = unsigned16_to_signed(read2) # 121
public override void _Ready()
{
using var f = FileAccess.Open("user://file.dat", FileAccess.ModeFlags.WriteRead);
f.Store16(unchecked((ushort)-42)); // 环绕存储 65494 (2^16 - 42).
f.Store16(121); // 在有效范围内，容量为 121 。
f.Seek(0); // 回到起始位置，重新读取存储的值。
ushort read1 = f.Get16(); // 65494
ushort read2 = f.Get16(); // 121
short converted1 = (short)read1; // -42
short converted2 = (short)read2; // 121
}
将整数存储为文件中的32位。
注意：value应该位于区间[0,2^32-1]中。任何其他值都会溢出并环绕。
注意：如果发生错误，则文件位置指示符的结果值不确定。
要存储有符号整数，请使用store_64()，或手动转换它（有关示例，请参阅store_16()）。
将整数存储为文件中的64位。
注意：value必须位于区间[-2^63,2^63-1]（即为有效的int值）。
注意：如果发生错误，则文件位置指示符的结果值不确定。
bool store_buffer(buffer: PackedByteArray) 🔗
将给定的字节数组存储在文件中。
注意：如果发生错误，则文件位置指示符的结果值不确定。
bool store_csv_line(values: PackedStringArray, delim: String = ",") 🔗
将给定的PackedStringArray存储在文件中，作为CSV（逗号分隔值）格式的行。您可以传递不同的分隔符delim来使用，而不是默认的","（逗号）。此分隔符必须为一个字符长。
文本将被编码为UTF-8。
注意：如果发生错误，则文件位置指示符的结果值不确定。
bool store_double(value: float) 🔗
将浮点数存储为文件中的64位。
注意：如果发生错误，则文件位置指示符的结果值不确定。
bool store_float(value: float) 🔗
将浮点数存储为文件中的32位。
注意：如果发生错误，则文件位置指示符的结果值不确定。
bool store_half(value: float) 🔗
将半精度浮点数存储为文件中的16位。
bool store_line(line: String) 🔗
将line存储到文件中，后接一个换行符（\n），使用UTF-8编码。
注意：如果发生错误，文件位置指示器的值是不确定的。
bool store_pascal_string(string: String) 🔗
将给定的String以Pascal格式存储为文件中的一行（即还存储字符串的长度）。
文本将被编码为UTF-8。
注意：如果发生错误，则文件位置指示符的结果值不确定。
bool store_real(value: float) 🔗
在文件中存储浮点数。
注意：如果发生错误，则文件位置指示符的结果值不确定。
bool store_string(string: String) 🔗
将string存储到文件中，不使用换行符（\n），使用UTF-8编码。
注意：此方法旨在用于编写文本文件。字符串以UTF-8编码的缓冲区形式存储，没有字符串长度或结尾的零，这意味着无法轻松加载回来。如果要在二进制文件中存储可检索的字符串，请考虑使用store_pascal_string()代替。若要从文本文件中检索字符串，您可以使用get_buffer(length).get_string_from_utf8()（如果您知道长度）或get_as_text()。
注意：如果发生错误，文件位置指示器的结果值是不确定的。
bool store_var(value: Variant, full_objects: bool = false) 🔗
在文件中存储任何Variant值。如果full_objects为true，则允许编码对象（并且可能包含代码）。
在内部，这使用与@GlobalScope.var_to_bytes()方法相同的编码机制。
注意：并非所有属性都包括在内。只有使用@GlobalScope.PROPERTY_USAGE_STORAGE标志集配置的属性才会被序列化。您可以通过覆盖类中的Object._get_property_list()方法向属性添加新的使用标志。您还可以通过调用Object._get_property_list()检查属性使用是如何配置的。有关可能的使用标志，请参阅PropertyUsageFlags。
注意：如果发生错误，则文件位置指示符的结果值不确定。