godotengine/godot-docs-l10n
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs-l10n.git synced 2025-12-31 09:49:22 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
4.x
godot-docs-l10n/classes/zh_Hans/class_fileaccess.rst
Rémi Verschelde c3f2364c10 Sync classref with 4.6 branch 
Lots of translations invalidated (fuzzied) as we just synced Weblate.
2025-12-19 16:39:51 +01:00

1488 lines
101 KiB
ReStructuredText
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

:github_url: hide
.. _class_FileAccess:
FileAccess
==========
**继承：** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`
提供用于文件读写操作的方法。
.. rst-class:: classref-introduction-group
描述
----
这个类可以用于在用户设备的文件系统中永久存储数据，也可以从中读取数据。适用于存储游戏存档数据或玩家配置文件。
\ **示例：**\ 如何读写文件。\ :doc:`《数据路径》 <../tutorials/io/data_paths>`\ 文档中提到的用户数据文件夹中会存储一个名叫 ``"save_game.dat"`` 的文件：
.. tabs::
.. code-tab:: gdscript
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
.. code-tab:: csharp
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;
}
\ **FileAccess** 实例拥有自己的文件游标，它是文件中下一次读/写操作将发生的位置（单位为字节）。诸如 :ref:`get_8()<class_FileAccess_method_get_8>`\ 、\ :ref:`get_16()<class_FileAccess_method_get_16>`\ 、\ :ref:`store_8()<class_FileAccess_method_store_8>` 和 :ref:`store_16()<class_FileAccess_method_store_16>` 等函数会将文件游标向前移动读/写的字节数。可以使用 :ref:`seek()<class_FileAccess_method_seek>` 或 :ref:`seek_end()<class_FileAccess_method_seek_end>` 将文件游标移动到特定位置，且可以使用 :ref:`get_position()<class_FileAccess_method_get_position>` 获取其位置。
\ **FileAccess** 实例被释放时会关闭对应的文件。由于这个类继承自 :ref:`RefCounted<class_RefCounted>`\ ，不再使用实例时会自动触发该行为。可以使用 :ref:`close()<class_FileAccess_method_close>` 在此之前显式关闭。在 C# 中引用必须手动释放，可以通过 ``using`` 语句或直接调用 ``Dispose`` 方法来完成。
\ **注意：**\ 要在导出后访问项目资源，建议使用 :ref:`ResourceLoader<class_ResourceLoader>` 而不是 **FileAccess**\ ，因为有些文件已被转换为特定于引擎的格式，并且它们的原始源文件可能并不存在于导出的 PCK 包中。如果使用 **FileAccess**\ ，请确保通过在导入面板中将其导入模式更改为\ **保留文件（按原样导出）**\ 来将文件包含在导出中；或者对于没有此选项的文件，请在导出对话框中更改非资源导出筛选器，加上文件的扩展名（例如 ``*.txt``\ ）。
\ **注意：**\ 只有当进程“正常”退出时（例如通过单击窗口管理器的关闭按钮或按 :kbd:`Alt + F4`\ ），文件才会自动关闭。如果在项目运行时按 :kbd:`F8` 停止项目执行，则不会关闭文件，因为游戏进程将被中止。可以通过定期调用 :ref:`flush()<class_FileAccess_method_flush>` 来解决这个问题。
.. rst-class:: classref-introduction-group
教程
----
- :doc:`文件系统 <../tutorials/scripting/filesystem>`
- :doc:`运行时文件加载与保存 <../tutorials/io/runtime_file_loading_and_saving>`
- :doc:`二进制序列化 API <../tutorials/io/binary_serialization_api>`
- `3D 体素演示 <https://godotengine.org/asset-library/asset/2755>`__
.. rst-class:: classref-reftable-group
属性
----
.. table::
:widths: auto
+-------------------------+---------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`big_endian<class_FileAccess_property_big_endian>` |
+-------------------------+---------------------------------------------------------+
.. rst-class:: classref-reftable-group
方法
----
.. table::
:widths: auto
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`close<class_FileAccess_method_close>`\ (\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`FileAccess<class_FileAccess>` | :ref:`create_temp<class_FileAccess_method_create_temp>`\ (\ mode_flags\: :ref:`int<class_int>`, prefix\: :ref:`String<class_String>` = "", extension\: :ref:`String<class_String>` = "", keep\: :ref:`bool<class_bool>` = false\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`eof_reached<class_FileAccess_method_eof_reached>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`file_exists<class_FileAccess_method_file_exists>`\ (\ path\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`flush<class_FileAccess_method_flush>`\ (\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_8<class_FileAccess_method_get_8>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_16<class_FileAccess_method_get_16>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_32<class_FileAccess_method_get_32>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_64<class_FileAccess_method_get_64>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_access_time<class_FileAccess_method_get_access_time>`\ (\ file\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`get_as_text<class_FileAccess_method_get_as_text>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`PackedByteArray<class_PackedByteArray>` | :ref:`get_buffer<class_FileAccess_method_get_buffer>`\ (\ length\: :ref:`int<class_int>`\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`PackedStringArray<class_PackedStringArray>` | :ref:`get_csv_line<class_FileAccess_method_get_csv_line>`\ (\ delim\: :ref:`String<class_String>` = ","\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>` | :ref:`get_double<class_FileAccess_method_get_double>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`get_error<class_FileAccess_method_get_error>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`PackedByteArray<class_PackedByteArray>` | :ref:`get_extended_attribute<class_FileAccess_method_get_extended_attribute>`\ (\ file\: :ref:`String<class_String>`, attribute_name\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`get_extended_attribute_string<class_FileAccess_method_get_extended_attribute_string>`\ (\ file\: :ref:`String<class_String>`, attribute_name\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`PackedStringArray<class_PackedStringArray>` | :ref:`get_extended_attributes_list<class_FileAccess_method_get_extended_attributes_list>`\ (\ file\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`PackedByteArray<class_PackedByteArray>` | :ref:`get_file_as_bytes<class_FileAccess_method_get_file_as_bytes>`\ (\ path\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`get_file_as_string<class_FileAccess_method_get_file_as_string>`\ (\ path\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>` | :ref:`get_float<class_FileAccess_method_get_float>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>` | :ref:`get_half<class_FileAccess_method_get_half>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`get_hidden_attribute<class_FileAccess_method_get_hidden_attribute>`\ (\ file\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_length<class_FileAccess_method_get_length>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`get_line<class_FileAccess_method_get_line>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`get_md5<class_FileAccess_method_get_md5>`\ (\ path\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_modified_time<class_FileAccess_method_get_modified_time>`\ (\ file\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`get_open_error<class_FileAccess_method_get_open_error>`\ (\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`get_pascal_string<class_FileAccess_method_get_pascal_string>`\ (\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`get_path<class_FileAccess_method_get_path>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`get_path_absolute<class_FileAccess_method_get_path_absolute>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_position<class_FileAccess_method_get_position>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`get_read_only_attribute<class_FileAccess_method_get_read_only_attribute>`\ (\ file\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>` | :ref:`get_real<class_FileAccess_method_get_real>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`get_sha256<class_FileAccess_method_get_sha256>`\ (\ path\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_size<class_FileAccess_method_get_size>`\ (\ file\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |bitfield|\[:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>`\] | :ref:`get_unix_permissions<class_FileAccess_method_get_unix_permissions>`\ (\ file\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>` | :ref:`get_var<class_FileAccess_method_get_var>`\ (\ allow_objects\: :ref:`bool<class_bool>` = false\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`is_open<class_FileAccess_method_is_open>`\ (\ ) |const| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`FileAccess<class_FileAccess>` | :ref:`open<class_FileAccess_method_open>`\ (\ path\: :ref:`String<class_String>`, flags\: :ref:`ModeFlags<enum_FileAccess_ModeFlags>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`FileAccess<class_FileAccess>` | :ref:`open_compressed<class_FileAccess_method_open_compressed>`\ (\ path\: :ref:`String<class_String>`, mode_flags\: :ref:`ModeFlags<enum_FileAccess_ModeFlags>`, compression_mode\: :ref:`CompressionMode<enum_FileAccess_CompressionMode>` = 0\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`FileAccess<class_FileAccess>` | :ref:`open_encrypted<class_FileAccess_method_open_encrypted>`\ (\ path\: :ref:`String<class_String>`, mode_flags\: :ref:`ModeFlags<enum_FileAccess_ModeFlags>`, key\: :ref:`PackedByteArray<class_PackedByteArray>`, iv\: :ref:`PackedByteArray<class_PackedByteArray>` = PackedByteArray()\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`FileAccess<class_FileAccess>` | :ref:`open_encrypted_with_pass<class_FileAccess_method_open_encrypted_with_pass>`\ (\ path\: :ref:`String<class_String>`, mode_flags\: :ref:`ModeFlags<enum_FileAccess_ModeFlags>`, pass\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`remove_extended_attribute<class_FileAccess_method_remove_extended_attribute>`\ (\ file\: :ref:`String<class_String>`, attribute_name\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`resize<class_FileAccess_method_resize>`\ (\ length\: :ref:`int<class_int>`\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`seek<class_FileAccess_method_seek>`\ (\ position\: :ref:`int<class_int>`\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`seek_end<class_FileAccess_method_seek_end>`\ (\ position\: :ref:`int<class_int>` = 0\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`set_extended_attribute<class_FileAccess_method_set_extended_attribute>`\ (\ file\: :ref:`String<class_String>`, attribute_name\: :ref:`String<class_String>`, data\: :ref:`PackedByteArray<class_PackedByteArray>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`set_extended_attribute_string<class_FileAccess_method_set_extended_attribute_string>`\ (\ file\: :ref:`String<class_String>`, attribute_name\: :ref:`String<class_String>`, data\: :ref:`String<class_String>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`set_hidden_attribute<class_FileAccess_method_set_hidden_attribute>`\ (\ file\: :ref:`String<class_String>`, hidden\: :ref:`bool<class_bool>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`set_read_only_attribute<class_FileAccess_method_set_read_only_attribute>`\ (\ file\: :ref:`String<class_String>`, ro\: :ref:`bool<class_bool>`\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`set_unix_permissions<class_FileAccess_method_set_unix_permissions>`\ (\ file\: :ref:`String<class_String>`, permissions\: |bitfield|\[:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>`\]\ ) |static| |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`store_8<class_FileAccess_method_store_8>`\ (\ value\: :ref:`int<class_int>`\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`store_16<class_FileAccess_method_store_16>`\ (\ value\: :ref:`int<class_int>`\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`store_32<class_FileAccess_method_store_32>`\ (\ value\: :ref:`int<class_int>`\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`store_64<class_FileAccess_method_store_64>`\ (\ value\: :ref:`int<class_int>`\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`store_buffer<class_FileAccess_method_store_buffer>`\ (\ buffer\: :ref:`PackedByteArray<class_PackedByteArray>`\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`store_csv_line<class_FileAccess_method_store_csv_line>`\ (\ values\: :ref:`PackedStringArray<class_PackedStringArray>`, delim\: :ref:`String<class_String>` = ","\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`store_double<class_FileAccess_method_store_double>`\ (\ value\: :ref:`float<class_float>`\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`store_float<class_FileAccess_method_store_float>`\ (\ value\: :ref:`float<class_float>`\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`store_half<class_FileAccess_method_store_half>`\ (\ value\: :ref:`float<class_float>`\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`store_line<class_FileAccess_method_store_line>`\ (\ line\: :ref:`String<class_String>`\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`store_pascal_string<class_FileAccess_method_store_pascal_string>`\ (\ string\: :ref:`String<class_String>`\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`store_real<class_FileAccess_method_store_real>`\ (\ value\: :ref:`float<class_float>`\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`store_string<class_FileAccess_method_store_string>`\ (\ string\: :ref:`String<class_String>`\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`store_var<class_FileAccess_method_store_var>`\ (\ value\: :ref:`Variant<class_Variant>`, full_objects\: :ref:`bool<class_bool>` = false\ ) |
+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
枚举
----
.. _enum_FileAccess_ModeFlags:
.. rst-class:: classref-enumeration
enum **ModeFlags**: :ref:`🔗<enum_FileAccess_ModeFlags>`
.. _class_FileAccess_constant_READ:
.. rst-class:: classref-enumeration-constant
:ref:`ModeFlags<enum_FileAccess_ModeFlags>` **READ** = ``1``
打开文件进行读取操作。文件游标位于文件的开头。
.. _class_FileAccess_constant_WRITE:
.. rst-class:: classref-enumeration-constant
:ref:`ModeFlags<enum_FileAccess_ModeFlags>` **WRITE** = ``2``
Opens the file for write operations. If the file exists, it is truncated to zero length and its contents are cleared. Otherwise, it is created.
\ **Note:** When creating a file it must be in an already existing directory. To recursively create directories for a file path, see :ref:`DirAccess.make_dir_recursive()<class_DirAccess_method_make_dir_recursive>`.
.. _class_FileAccess_constant_READ_WRITE:
.. rst-class:: classref-enumeration-constant
:ref:`ModeFlags<enum_FileAccess_ModeFlags>` **READ_WRITE** = ``3``
打开文件进行读写操作。不会截断文件。文件游标位于文件的开头。
.. _class_FileAccess_constant_WRITE_READ:
.. rst-class:: classref-enumeration-constant
:ref:`ModeFlags<enum_FileAccess_ModeFlags>` **WRITE_READ** = ``7``
Opens the file for read and write operations. If the file exists, it is truncated to zero length and its contents are cleared. Otherwise, it is created. The file cursor is positioned at the beginning of the file.
\ **Note:** When creating a file it must be in an already existing directory. To recursively create directories for a file path, see :ref:`DirAccess.make_dir_recursive()<class_DirAccess_method_make_dir_recursive>`.
.. rst-class:: classref-item-separator
----
.. _enum_FileAccess_CompressionMode:
.. rst-class:: classref-enumeration
enum **CompressionMode**: :ref:`🔗<enum_FileAccess_CompressionMode>`
.. _class_FileAccess_constant_COMPRESSION_FASTLZ:
.. rst-class:: classref-enumeration-constant
:ref:`CompressionMode<enum_FileAccess_CompressionMode>` **COMPRESSION_FASTLZ** = ``0``
使用 `FastLZ <https://fastlz.org/>`__ 压缩方法。
.. _class_FileAccess_constant_COMPRESSION_DEFLATE:
.. rst-class:: classref-enumeration-constant
:ref:`CompressionMode<enum_FileAccess_CompressionMode>` **COMPRESSION_DEFLATE** = ``1``
使用 `DEFLATE <https://en.wikipedia.org/wiki/DEFLATE>`__ 压缩方法。
.. _class_FileAccess_constant_COMPRESSION_ZSTD:
.. rst-class:: classref-enumeration-constant
:ref:`CompressionMode<enum_FileAccess_CompressionMode>` **COMPRESSION_ZSTD** = ``2``
使用 `Zstandard <https://facebook.github.io/zstd/>`__ 压缩方法。
.. _class_FileAccess_constant_COMPRESSION_GZIP:
.. rst-class:: classref-enumeration-constant
:ref:`CompressionMode<enum_FileAccess_CompressionMode>` **COMPRESSION_GZIP** = ``3``
使用 `gzip <https://www.gzip.org/>`__ 压缩方法。
.. _class_FileAccess_constant_COMPRESSION_BROTLI:
.. rst-class:: classref-enumeration-constant
:ref:`CompressionMode<enum_FileAccess_CompressionMode>` **COMPRESSION_BROTLI** = ``4``
使用 `brotli <https://github.com/google/brotli>`__ 压缩方法（仅支持解压缩）。
.. rst-class:: classref-item-separator
----
.. _enum_FileAccess_UnixPermissionFlags:
.. rst-class:: classref-enumeration
flags **UnixPermissionFlags**: :ref:`🔗<enum_FileAccess_UnixPermissionFlags>`
.. _class_FileAccess_constant_UNIX_READ_OWNER:
.. rst-class:: classref-enumeration-constant
:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>` **UNIX_READ_OWNER** = ``256``
读取所有者比特位。
.. _class_FileAccess_constant_UNIX_WRITE_OWNER:
.. rst-class:: classref-enumeration-constant
:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>` **UNIX_WRITE_OWNER** = ``128``
写入所有者比特位。
.. _class_FileAccess_constant_UNIX_EXECUTE_OWNER:
.. rst-class:: classref-enumeration-constant
:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>` **UNIX_EXECUTE_OWNER** = ``64``
执行所有者比特位。
.. _class_FileAccess_constant_UNIX_READ_GROUP:
.. rst-class:: classref-enumeration-constant
:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>` **UNIX_READ_GROUP** = ``32``
读取组比特位。
.. _class_FileAccess_constant_UNIX_WRITE_GROUP:
.. rst-class:: classref-enumeration-constant
:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>` **UNIX_WRITE_GROUP** = ``16``
写入组比特位。
.. _class_FileAccess_constant_UNIX_EXECUTE_GROUP:
.. rst-class:: classref-enumeration-constant
:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>` **UNIX_EXECUTE_GROUP** = ``8``
执行组比特位。
.. _class_FileAccess_constant_UNIX_READ_OTHER:
.. rst-class:: classref-enumeration-constant
:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>` **UNIX_READ_OTHER** = ``4``
读取其他比特位。
.. _class_FileAccess_constant_UNIX_WRITE_OTHER:
.. rst-class:: classref-enumeration-constant
:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>` **UNIX_WRITE_OTHER** = ``2``
写入其他比特位。
.. _class_FileAccess_constant_UNIX_EXECUTE_OTHER:
.. rst-class:: classref-enumeration-constant
:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>` **UNIX_EXECUTE_OTHER** = ``1``
执行其他比特位。
.. _class_FileAccess_constant_UNIX_SET_USER_ID:
.. rst-class:: classref-enumeration-constant
:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>` **UNIX_SET_USER_ID** = ``2048``
在执行比特位上设置用户 ID 。
.. _class_FileAccess_constant_UNIX_SET_GROUP_ID:
.. rst-class:: classref-enumeration-constant
:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>` **UNIX_SET_GROUP_ID** = ``1024``
在执行位上设置组 ID。
.. _class_FileAccess_constant_UNIX_RESTRICTED_DELETE:
.. rst-class:: classref-enumeration-constant
:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>` **UNIX_RESTRICTED_DELETE** = ``512``
限制删除（粘性）比特位。
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
属性说明
--------
.. _class_FileAccess_property_big_endian:
.. rst-class:: classref-property
:ref:`bool<class_bool>` **big_endian** :ref:`🔗<class_FileAccess_property_big_endian>`
.. rst-class:: classref-property-setget
- |void| **set_big_endian**\ (\ value\: :ref:`bool<class_bool>`\ )
- :ref:`bool<class_bool>` **is_big_endian**\ (\ )
如果为 ``true``\ ，则文件用大端\ `字节序 <https://zh.wikipedia.org/wiki/%E5%AD%97%E8%8A%82%E5%BA%8F>`__\ 读取。如果为 ``false``\ ，则文件以小端字节序读取。如果有疑问，请将其保留为 ``false``\ ，因为大多数文件都是用小端字节序编写的。
\ **注意：**\ 每当打开文件时，该选项总会重置为系统字节序，在支持的所有平台上均为小端序。因此必须在打开文件\ *之后*\ 设置 :ref:`big_endian<class_FileAccess_property_big_endian>`\ ，而不是之前。
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
方法说明
--------
.. _class_FileAccess_method_close:
.. rst-class:: classref-method
|void| **close**\ (\ ) :ref:`🔗<class_FileAccess_method_close>`
关闭当前打开的文件，阻止后续的读写操作。如果要将数据持久化到磁盘而不关闭文件，请使用 :ref:`flush()<class_FileAccess_method_flush>`\ 。
\ **注意：**\ **FileAccess** 被释放时会自动关闭，释放发生在离开作用域或被赋值为 ``null`` 时。在 C# 中，使用完后必须弃置该引用，可以使用 ``using`` 语句或直接调用 ``Dispose`` 方法。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_create_temp:
.. rst-class:: classref-method
:ref:`FileAccess<class_FileAccess>` **create_temp**\ (\ mode_flags\: :ref:`int<class_int>`, prefix\: :ref:`String<class_String>` = "", extension\: :ref:`String<class_String>` = "", keep\: :ref:`bool<class_bool>` = false\ ) |static| :ref:`🔗<class_FileAccess_method_create_temp>`
创建临时文件。该文件将在返回的 **FileAccess** 释放时释放。
如果 ``prefix`` 非空，则会将其添加为文件名的前缀，用 ``-`` 分隔。
如果 ``extension`` 非空，则会将其追加到临时文件名之后。
如果 ``keep`` 为 ``true``\ ，则在返回的 **FileAccess** 释放时不会删除该文件。
如果打开文件失败则返回 ``null``\ ，可以使用 :ref:`get_open_error()<class_FileAccess_method_get_open_error>` 检查发生的错误。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_eof_reached:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **eof_reached**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_eof_reached>`
如果文件光标已经读到了文件末尾，则返回 ``true``\ 。
\ **注意：**\ ``eof_reached() == false`` 不能用于检查是否有更多可用数据。要在有更多可用数据时循环，请使用：
.. tabs::
.. code-tab:: gdscript
while file.get_position() < file.get_length():
# 读取数据
.. code-tab:: csharp
while (file.GetPosition() < file.GetLength())
{
// 读取数据
}
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_file_exists:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **file_exists**\ (\ path\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_file_exists>`
如果文件存在于给定路径中，则返回 ``true``\ 。
\ **注意：**\ 许多资源类型是导入的（例如纹理或声音文件），它们的源资产不会包含在导出的游戏中，因为只使用导入的版本。有关考虑资源重新映射的替代方法，请参阅 :ref:`ResourceLoader.exists()<class_ResourceLoader_method_exists>`\ 。
对于非静态的相对等效项，请使用 :ref:`DirAccess.file_exists()<class_DirAccess_method_file_exists>`\ 。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_flush:
.. rst-class:: classref-method
|void| **flush**\ (\ ) :ref:`🔗<class_FileAccess_method_flush>`
将文件的缓冲区写入磁盘。当关闭文件时，会自动进行刷新。这意味着你不需要在关闭文件前手动调用 :ref:`flush()<class_FileAccess_method_flush>`\ 。尽管如此，即使项目崩溃而不是正常关闭，调用 :ref:`flush()<class_FileAccess_method_flush>` 仍可用于确保数据安全。
\ **注意：**\ 只有在你真正需要的时候才调用 :ref:`flush()<class_FileAccess_method_flush>`\ 。否则，它会因不断的磁盘写入而降低性能。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_8:
.. rst-class:: classref-method
:ref:`int<class_int>` **get_8**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_8>`
以整数形式返回文件中接下来的 8 位。文件游标前进 1 个字节。请参阅 :ref:`store_8()<class_FileAccess_method_store_8>`\ ，详细了解哪些值可以通过这种方式存储和检索。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_16:
.. rst-class:: classref-method
:ref:`int<class_int>` **get_16**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_16>`
以整数形式返回文件中接下来的 16 位。文件游标前进 2 个字节。请参阅 :ref:`store_16()<class_FileAccess_method_store_16>`\ ，以获取有关可以通过这种方式存储和检索哪些值的详细信息。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_32:
.. rst-class:: classref-method
:ref:`int<class_int>` **get_32**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_32>`
以整数形式返回文件中接下来的 32 位。文件游标前进 4 个字节。请参阅 :ref:`store_32()<class_FileAccess_method_store_32>`\ ，以获取有关可以通过这种方式存储和检索哪些值的详细信息。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_64:
.. rst-class:: classref-method
:ref:`int<class_int>` **get_64**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_64>`
以整数形式返回文件中接下来的 64 位。文件游标前进 8 个字节。请参阅 :ref:`store_64()<class_FileAccess_method_store_64>`\ ，以获取有关可以通过这种方式存储和检索哪些值的详细信息。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_access_time:
.. rst-class:: classref-method
:ref:`int<class_int>` **get_access_time**\ (\ file\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_get_access_time>`
返回文件 ``file`` 的最后修改时间，使用 Unix 时间戳格式，出错时返回 ``0``\ 。这个 Unix 时间戳可以用 :ref:`Time<class_Time>` 单例转换为其他格式。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_as_text:
.. rst-class:: classref-method
:ref:`String<class_String>` **get_as_text**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_as_text>`
Returns the whole file as a :ref:`String<class_String>`. Text is interpreted as being UTF-8 encoded. This ignores the file cursor and does not affect it.
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_buffer:
.. rst-class:: classref-method
:ref:`PackedByteArray<class_PackedByteArray>` **get_buffer**\ (\ length\: :ref:`int<class_int>`\ ) |const| :ref:`🔗<class_FileAccess_method_get_buffer>`
将文件中接下来的 ``length`` 个字节作为 :ref:`PackedByteArray<class_PackedByteArray>` 返回。文件游标前进 ``length`` 个字节。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_csv_line:
.. rst-class:: classref-method
:ref:`PackedStringArray<class_PackedStringArray>` **get_csv_line**\ (\ delim\: :ref:`String<class_String>` = ","\ ) |const| :ref:`🔗<class_FileAccess_method_get_csv_line>`
以 CSV（逗号分隔值）格式返回文件的下一个值。可以传递不同的分隔符 ``delim``\ ，以使用默认 ``","``\ （逗号）以外的其他分隔符。这个分隔符必须为一个字符长，且不能是双引号。
文本被解析为 UTF-8 编码。如果文本值包含分隔符，则它们必须用双引号引起来。文本值中的双引号可以通过将它们的出现次数加倍来转义。文件游标前进至行尾的换行符后。
例如，以下 CSV 行是有效的，每行将被正确解析为两个字符串：
.. code:: text
Alice,"Hello, Bob!"
Bob,Alice! What a surprise!
Alice,"I thought you'd reply with ""Hello, world""."
请注意第二行如何省略封闭的引号，因为它不包含分隔符。然而它\ *可以*\ 很好地使用引号，它只是为了演示目的而没有编写。第三行必须为每个需要被解析为引号而不是文本值的末尾而使用 ``""``\ 。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_double:
.. rst-class:: classref-method
:ref:`float<class_float>` **get_double**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_double>`
将文件中接下来的 64 位作为浮点数返回。文件游标前进 8 个字节。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_error:
.. rst-class:: classref-method
:ref:`Error<enum_@GlobalScope_Error>` **get_error**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_error>`
返回试图执行操作时发生的最后一个错误。请与 :ref:`Error<enum_@GlobalScope_Error>` 中的 ``ERR_FILE_*`` 常量比较。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_extended_attribute:
.. rst-class:: classref-method
:ref:`PackedByteArray<class_PackedByteArray>` **get_extended_attribute**\ (\ file\: :ref:`String<class_String>`, attribute_name\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_get_extended_attribute>`
Reads the file extended attribute with name ``attribute_name`` as a byte array.
\ **Note:** This method is implemented on Linux, macOS, and Windows.
\ **Note:** Extended attributes support depends on the file system. Attributes will be lost when the file is moved between incompatible file systems.
\ **Note:** On Linux, only "user" namespace attributes are accessible, namespace prefix should not be included.
\ **Note:** On Windows, alternate data streams are used to store extended attributes.
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_extended_attribute_string:
.. rst-class:: classref-method
:ref:`String<class_String>` **get_extended_attribute_string**\ (\ file\: :ref:`String<class_String>`, attribute_name\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_get_extended_attribute_string>`
Reads the file extended attribute with name ``attribute_name`` as a UTF-8 encoded string.
\ **Note:** This method is implemented on Linux, macOS, and Windows.
\ **Note:** Extended attributes support depends on the file system. Attributes will be lost when the file is moved between incompatible file systems.
\ **Note:** On Linux, only "user" namespace attributes are accessible, namespace prefix should not be included.
\ **Note:** On Windows, alternate data streams are used to store extended attributes.
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_extended_attributes_list:
.. rst-class:: classref-method
:ref:`PackedStringArray<class_PackedStringArray>` **get_extended_attributes_list**\ (\ file\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_get_extended_attributes_list>`
Returns a list of file extended attributes.
\ **Note:** This method is implemented on Linux, macOS, and Windows.
\ **Note:** Extended attributes support depends on the file system. Attributes will be lost when the file is moved between incompatible file systems.
\ **Note:** On Linux, only "user" namespace attributes are accessible, namespace prefix should not be included.
\ **Note:** On Windows, alternate data streams are used to store extended attributes.
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_file_as_bytes:
.. rst-class:: classref-method
:ref:`PackedByteArray<class_PackedByteArray>` **get_file_as_bytes**\ (\ path\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_get_file_as_bytes>`
将整个 ``path`` 文件内容作为 :ref:`PackedByteArray<class_PackedByteArray>` 返回，无需任何解码。
如果打开文件时发生错误，则返回空的 :ref:`PackedByteArray<class_PackedByteArray>`\ 。你可以使用 :ref:`get_open_error()<class_FileAccess_method_get_open_error>` 来检查发生的错误。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_file_as_string:
.. rst-class:: classref-method
:ref:`String<class_String>` **get_file_as_string**\ (\ path\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_get_file_as_string>`
将整个 ``path`` 文件内容以 :ref:`String<class_String>` 形式返回。文本被解释为 UTF-8 编码。
如果打开文件时发生错误，则返回空 :ref:`String<class_String>`\ 。可以使用 :ref:`get_open_error()<class_FileAccess_method_get_open_error>` 来检查发生的错误。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_float:
.. rst-class:: classref-method
:ref:`float<class_float>` **get_float**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_float>`
将文件中接下来的 32 位作为浮点数返回。文件游标前进 4 个字节。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_half:
.. rst-class:: classref-method
:ref:`float<class_float>` **get_half**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_half>`
将文件中接下来的 16 位作为半精度浮点数返回。文件游标前进 2 个字节。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_hidden_attribute:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **get_hidden_attribute**\ (\ file\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_get_hidden_attribute>`
Returns ``true`` if the **hidden** attribute is set on the file at the given path.
\ **Note:** This method is implemented on iOS, BSD, macOS, and Windows.
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_length:
.. rst-class:: classref-method
:ref:`int<class_int>` **get_length**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_length>`
返回文件的大小，单位为字节。如果是管道，则返回可以从管道中读取的字节数。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_line:
.. rst-class:: classref-method
:ref:`String<class_String>` **get_line**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_line>`
以 :ref:`String<class_String>` 的形式返回文件中的下一行。返回的字符串不包含换行符（\ ``\n``\ ）和回车符（\ ``\r``\ ），但是会包含开头和结尾的其他空白字符。文件游标前进至行尾的换行符之后。
文本按照 UTF-8 编码规则进行解析。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_md5:
.. rst-class:: classref-method
:ref:`String<class_String>` **get_md5**\ (\ path\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_get_md5>`
返回一个给定路径文件的 MD5 字符串，如果失败则返回一个空的 :ref:`String<class_String>`\ 。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_modified_time:
.. rst-class:: classref-method
:ref:`int<class_int>` **get_modified_time**\ (\ file\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_get_modified_time>`
返回 ``file`` 的最后修改时间，使用 Unix 时间戳格式，出错时返回 ``0``\ 。这个 Unix 时间戳可以用 :ref:`Time<class_Time>` 单例转换为其他格式。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_open_error:
.. rst-class:: classref-method
:ref:`Error<enum_@GlobalScope_Error>` **get_open_error**\ (\ ) |static| :ref:`🔗<class_FileAccess_method_get_open_error>`
返回当前线程中最后一次 :ref:`open()<class_FileAccess_method_open>` 调用的结果。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_pascal_string:
.. rst-class:: classref-method
:ref:`String<class_String>` **get_pascal_string**\ (\ ) :ref:`🔗<class_FileAccess_method_get_pascal_string>`
返回文件中的一个以 Pascal 格式保存的 :ref:`String<class_String>`\ ，即字符串的长度在开头显式存储。见 :ref:`store_pascal_string()<class_FileAccess_method_store_pascal_string>`\ 。可能包含换行符。文件游标前进至读取的字节之后。
文本按照 UTF-8 编码规则进行解析。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_path:
.. rst-class:: classref-method
:ref:`String<class_String>` **get_path**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_path>`
返回当前打开的文件的路径为\ :ref:`String<class_String>`\ 。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_path_absolute:
.. rst-class:: classref-method
:ref:`String<class_String>` **get_path_absolute**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_path_absolute>`
返回当前打开的文件的绝对路径为\ :ref:`String<class_String>`\ 。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_position:
.. rst-class:: classref-method
:ref:`int<class_int>` **get_position**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_position>`
返回文件游标的位置，单位为字节，相对于文件的开头。文件读写游标由 :ref:`seek()<class_FileAccess_method_seek>` 和 :ref:`seek_end()<class_FileAccess_method_seek_end>` 设置，读写操作会导致游标前进。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_read_only_attribute:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **get_read_only_attribute**\ (\ file\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_get_read_only_attribute>`
Returns ``true`` if the **read only** attribute is set on the file at the given path.
\ **Note:** This method is implemented on iOS, BSD, macOS, and Windows.
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_real:
.. rst-class:: classref-method
:ref:`float<class_float>` **get_real**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_get_real>`
返回文件中后续数据构成的一个浮点数。文件游标前进 4 个或 8 个字节，取决于保存文件的 Godot 构建所使用的精度。
如果保存文件的是使用 ``precision=single`` 编译的 Godot 构建（默认），则会从文件中读取 32 位。否则如果是使用 ``precision=double`` 编译的，那么读取的就是 64 位。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_sha256:
.. rst-class:: classref-method
:ref:`String<class_String>` **get_sha256**\ (\ path\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_get_sha256>`
返回一个表示给定路径下文件的 SHA-256 :ref:`String<class_String>`\ ，失败时返回一个空的 :ref:`String<class_String>`\ 。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_size:
.. rst-class:: classref-method
:ref:`int<class_int>` **get_size**\ (\ file\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_get_size>`
Returns the size of the file at the given path, in bytes, or ``-1`` on error.
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_unix_permissions:
.. rst-class:: classref-method
|bitfield|\[:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>`\] **get_unix_permissions**\ (\ file\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_get_unix_permissions>`
Returns the UNIX permissions of the file at the given path.
\ **Note:** This method is implemented on iOS, Linux/BSD, and macOS.
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_var:
.. rst-class:: classref-method
:ref:`Variant<class_Variant>` **get_var**\ (\ allow_objects\: :ref:`bool<class_bool>` = false\ ) |const| :ref:`🔗<class_FileAccess_method_get_var>`
返回文件中的下一个 :ref:`Variant<class_Variant>` 值。如果 ``allow_objects`` 为 ``true``\ ，则允许解码对象。这会使文件光标前进读取的字节数。
在内部，这使用与 :ref:`@GlobalScope.bytes_to_var()<class_@GlobalScope_method_bytes_to_var>` 方法相同的解码机制，如在\ :doc:`二进制序列化 API <../tutorials/io/binary_serialization_api>` 文档中所述。
\ **警告：**\ 反序列化得到的对象可能包含被执行的代码。如果序列化的对象来自不受信任的来源，请不要使用这个选项，以避免潜在的安全威胁，如远程代码执行。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_is_open:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **is_open**\ (\ ) |const| :ref:`🔗<class_FileAccess_method_is_open>`
如果文件当前被打开，返回 ``true``\ 。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_open:
.. rst-class:: classref-method
:ref:`FileAccess<class_FileAccess>` **open**\ (\ path\: :ref:`String<class_String>`, flags\: :ref:`ModeFlags<enum_FileAccess_ModeFlags>`\ ) |static| :ref:`🔗<class_FileAccess_method_open>`
创建一个新的 **FileAccess** 对象，会根据标志来确定以写入还是读取模式打开文件。
如果打开文件失败，则返回 ``null`` 。你可以使用 :ref:`get_open_error()<class_FileAccess_method_get_open_error>` 来检查发生的错误。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_open_compressed:
.. rst-class:: classref-method
:ref:`FileAccess<class_FileAccess>` **open_compressed**\ (\ path\: :ref:`String<class_String>`, mode_flags\: :ref:`ModeFlags<enum_FileAccess_ModeFlags>`, compression_mode\: :ref:`CompressionMode<enum_FileAccess_CompressionMode>` = 0\ ) |static| :ref:`🔗<class_FileAccess_method_open_compressed>`
创建一个新的 **FileAccess** 对象，并打开一个压缩文件以进行读取或写入。
\ **注意：**\ :ref:`open_compressed()<class_FileAccess_method_open_compressed>` 只能读取 Godot 保存的文件，不能读取第三方压缩格式。有关解决方法，请参阅 `GitHub 问题 #28999 <https://github.com/godotengine/godot/issues/28999>`__\ 。
如果打开文件失败，则返回 ``null``\ 。可以使用 :ref:`get_open_error()<class_FileAccess_method_get_open_error>` 来检查发生的错误。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_open_encrypted:
.. rst-class:: classref-method
:ref:`FileAccess<class_FileAccess>` **open_encrypted**\ (\ path\: :ref:`String<class_String>`, mode_flags\: :ref:`ModeFlags<enum_FileAccess_ModeFlags>`, key\: :ref:`PackedByteArray<class_PackedByteArray>`, iv\: :ref:`PackedByteArray<class_PackedByteArray>` = PackedByteArray()\ ) |static| :ref:`🔗<class_FileAccess_method_open_encrypted>`
创建一个新的 **FileAccess** 对象，并以写入或读取模式打开一个加密文件。需要传入一个二进制密钥来加密/解密它。
\ **注意：**\ 提供的密钥必须是 32 字节长。
如果打开文件失败，则返回 ``null``\ 。可以使用 :ref:`get_open_error()<class_FileAccess_method_get_open_error>` 来检查发生的错误。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_open_encrypted_with_pass:
.. rst-class:: classref-method
:ref:`FileAccess<class_FileAccess>` **open_encrypted_with_pass**\ (\ path\: :ref:`String<class_String>`, mode_flags\: :ref:`ModeFlags<enum_FileAccess_ModeFlags>`, pass\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_open_encrypted_with_pass>`
创建一个新的 **FileAccess** 对象，以写或读的模式打开一个加密文件。你需要传递一个密码来加密/解密它。
如果打开文件失败，则返回 ``null`` 。你可以使用 :ref:`get_open_error()<class_FileAccess_method_get_open_error>` 来检查发生的错误。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_remove_extended_attribute:
.. rst-class:: classref-method
:ref:`Error<enum_@GlobalScope_Error>` **remove_extended_attribute**\ (\ file\: :ref:`String<class_String>`, attribute_name\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_remove_extended_attribute>`
Removes file extended attribute with name ``attribute_name``.
\ **Note:** This method is implemented on Linux, macOS, and Windows.
\ **Note:** Extended attributes support depends on the file system. Attributes will be lost when the file is moved between incompatible file systems.
\ **Note:** On Linux, only "user" namespace attributes are accessible, namespace prefix should not be included.
\ **Note:** On Windows, alternate data streams are used to store extended attributes.
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_resize:
.. rst-class:: classref-method
:ref:`Error<enum_@GlobalScope_Error>` **resize**\ (\ length\: :ref:`int<class_int>`\ ) :ref:`🔗<class_FileAccess_method_resize>`
将文件大小修改为指定长度。文件必须使用允许写操作的模式打开。如果扩展了文件，则会追加 NUL 字符。如果截断了文件，则会丢弃从文件末尾到文件原长度之间的所有数据。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_seek:
.. rst-class:: classref-method
|void| **seek**\ (\ position\: :ref:`int<class_int>`\ ) :ref:`🔗<class_FileAccess_method_seek>`
Sets the file cursor to the specified position in bytes, from the beginning of the file. This changes the value returned by :ref:`get_position()<class_FileAccess_method_get_position>`.
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_seek_end:
.. rst-class:: classref-method
|void| **seek_end**\ (\ position\: :ref:`int<class_int>` = 0\ ) :ref:`🔗<class_FileAccess_method_seek_end>`
Sets the file cursor to the specified position in bytes, from the end of the file. This changes the value returned by :ref:`get_position()<class_FileAccess_method_get_position>`.
\ **Note:** This is an offset, so you should use negative numbers otherwise the file cursor will be at the end of the file.
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_set_extended_attribute:
.. rst-class:: classref-method
:ref:`Error<enum_@GlobalScope_Error>` **set_extended_attribute**\ (\ file\: :ref:`String<class_String>`, attribute_name\: :ref:`String<class_String>`, data\: :ref:`PackedByteArray<class_PackedByteArray>`\ ) |static| :ref:`🔗<class_FileAccess_method_set_extended_attribute>`
Writes file extended attribute with name ``attribute_name`` as a byte array.
\ **Note:** This method is implemented on Linux, macOS, and Windows.
\ **Note:** Extended attributes support depends on the file system. Attributes will be lost when the file is moved between incompatible file systems.
\ **Note:** On Linux, only "user" namespace attributes are accessible, namespace prefix should not be included.
\ **Note:** On Windows, alternate data streams are used to store extended attributes.
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_set_extended_attribute_string:
.. rst-class:: classref-method
:ref:`Error<enum_@GlobalScope_Error>` **set_extended_attribute_string**\ (\ file\: :ref:`String<class_String>`, attribute_name\: :ref:`String<class_String>`, data\: :ref:`String<class_String>`\ ) |static| :ref:`🔗<class_FileAccess_method_set_extended_attribute_string>`
Writes file extended attribute with name ``attribute_name`` as a UTF-8 encoded string.
\ **Note:** This method is implemented on Linux, macOS, and Windows.
\ **Note:** Extended attributes support depends on the file system. Attributes will be lost when the file is moved between incompatible file systems.
\ **Note:** On Linux, only "user" namespace attributes are accessible, namespace prefix should not be included.
\ **Note:** On Windows, alternate data streams are used to store extended attributes.
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_set_hidden_attribute:
.. rst-class:: classref-method
:ref:`Error<enum_@GlobalScope_Error>` **set_hidden_attribute**\ (\ file\: :ref:`String<class_String>`, hidden\: :ref:`bool<class_bool>`\ ) |static| :ref:`🔗<class_FileAccess_method_set_hidden_attribute>`
设置文件 **hidden** 属性。
\ **注意：**\ 该方法在 iOS、BSD、macOS 和 Windows 上实现。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_set_read_only_attribute:
.. rst-class:: classref-method
:ref:`Error<enum_@GlobalScope_Error>` **set_read_only_attribute**\ (\ file\: :ref:`String<class_String>`, ro\: :ref:`bool<class_bool>`\ ) |static| :ref:`🔗<class_FileAccess_method_set_read_only_attribute>`
设置文件 **read only** 属性。
\ **注意：**\ 该方法在 iOS、BSD、macOS 和 Windows 上实现。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_set_unix_permissions:
.. rst-class:: classref-method
:ref:`Error<enum_@GlobalScope_Error>` **set_unix_permissions**\ (\ file\: :ref:`String<class_String>`, permissions\: |bitfield|\[:ref:`UnixPermissionFlags<enum_FileAccess_UnixPermissionFlags>`\]\ ) |static| :ref:`🔗<class_FileAccess_method_set_unix_permissions>`
设置文件的 UNIX 权限。
\ **注意：**\ 该方法在 iOS、Linux/BSD 和 macOS 上实现。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_8:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **store_8**\ (\ value\: :ref:`int<class_int>`\ ) :ref:`🔗<class_FileAccess_method_store_8>`
将一个整数以 8 位形式存储在文件中。文件游标前进 1 个字节。如果操作成功则返回 ``true``\ 。
\ **注意：**\ ``value`` 应该位于 ``[0, 255]`` 的区间内。任何其他的值都会溢出并环绕。
\ **注意：**\ 出错时，文件位置标识符的取值不确定。
要存储有符号的整数，请使用 :ref:`store_64()<class_FileAccess_method_store_64>`\ ，或者手动转换（见 :ref:`store_16()<class_FileAccess_method_store_16>` 的例子）。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_16:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **store_16**\ (\ value\: :ref:`int<class_int>`\ ) :ref:`🔗<class_FileAccess_method_store_16>`
将一个整数以 16 位形式存储到文件中。文件游标前进 2 个字节。如果操作成功则返回 ``true``\ 。
\ **注意：**\ ``value`` 应该位于 ``[0, 2^16 - 1]`` 区间内。任何其他的值都会溢出并进行环绕。
\ **注意：**\ 出错时，文件位置标识符的取值不确定。
要存储有符号的整数，请使用 :ref:`store_64()<class_FileAccess_method_store_64>` 或者从区间 ``[-2^15, 2^15 - 1]`` 中存储一个有符号的整数（即保留一位作为符号），在读取时手动计算其符号。例如：
.. tabs::
.. code-tab:: gdscript
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
.. code-tab:: csharp
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
}
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_32:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **store_32**\ (\ value\: :ref:`int<class_int>`\ ) :ref:`🔗<class_FileAccess_method_store_32>`
将一个整数以 32 位形式存储到文件中。文件游标前进 4 个字节。如果操作成功则返回 ``true``\ 。
\ **注意：**\ ``value`` 应该位于 ``[0, 2^32 - 1]`` 区间内。任何其他的值都会溢出并环绕。
\ **注意：**\ 出错时，文件位置标识符的取值不确定。
要存储有符号的整数，请使用 :ref:`store_64()<class_FileAccess_method_store_64>`\ ，或者手动转换（见 :ref:`store_16()<class_FileAccess_method_store_16>` 的例子）。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_64:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **store_64**\ (\ value\: :ref:`int<class_int>`\ ) :ref:`🔗<class_FileAccess_method_store_64>`
将一个整数以 64 位形式存储到文件中。文件游标前进 8 个字节。如果操作成功则返回 ``true``\ 。
\ **注意：**\ ``value`` 必须位于 ``[-2^63, 2^63 - 1]`` 的区间内（即有效的 :ref:`int<class_int>` 值）。
\ **注意：**\ 出错时，文件位置标识符的取值不确定。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_buffer:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **store_buffer**\ (\ buffer\: :ref:`PackedByteArray<class_PackedByteArray>`\ ) :ref:`🔗<class_FileAccess_method_store_buffer>`
将给定的字节数组存储在文件中。文件游标前进写入的字节数。如果操作成功则返回 ``true``\ 。
\ **注意：**\ 出错时，文件位置标识符的取值不确定。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_csv_line:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **store_csv_line**\ (\ values\: :ref:`PackedStringArray<class_PackedStringArray>`, delim\: :ref:`String<class_String>` = ","\ ) :ref:`🔗<class_FileAccess_method_store_csv_line>`
Stores the given :ref:`PackedStringArray<class_PackedStringArray>` in the file as a line formatted in the CSV (Comma-Separated Values) format. You can pass a different delimiter ``delim`` to use other than the default ``","`` (comma). This delimiter must be one-character long.
Text will be encoded as UTF-8. Returns ``true`` if the operation is successful.
\ **Note:** If an error occurs, the resulting value of the file position indicator is indeterminate.
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_double:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **store_double**\ (\ value\: :ref:`float<class_float>`\ ) :ref:`🔗<class_FileAccess_method_store_double>`
将一个浮点数以 64 位的形式存储到文件中。文件游标前进 8 个字节。如果操作成功则返回 ``true``\ 。
\ **注意：**\ 出错时，文件位置标识符的取值不确定。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_float:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **store_float**\ (\ value\: :ref:`float<class_float>`\ ) :ref:`🔗<class_FileAccess_method_store_float>`
将一个浮点数以 32 位的形式存储到文件中。文件游标前进 4 个字节。如果操作成功则返回 ``true``\ 。
\ **注意：**\ 出错时，文件位置标识符的取值不确定。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_half:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **store_half**\ (\ value\: :ref:`float<class_float>`\ ) :ref:`🔗<class_FileAccess_method_store_half>`
将一个半精度浮点数以 16 位的形式存储到文件中。文件游标前进 2 个字节。如果操作成功则返回 ``true``\ 。
\ **注意：**\ 出错时，文件位置标识符的取值不确定。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_line:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **store_line**\ (\ line\: :ref:`String<class_String>`\ ) :ref:`🔗<class_FileAccess_method_store_line>`
将 ``line`` 存储到文件中，后跟一个换行符（\ ``\n``\ ），文本使用 UTF-8 编码。文件游标前进该行长度，至换行符后。写入的字节数取决于 UTF-8 编码后的字节，可能与 :ref:`String.length()<class_String_method_length>` 不同，后者计算的是 UTF-32 码位的数量。如果操作成功则返回 ``true``\ 。
\ **注意：**\ 出错时，文件位置标识符的取值不确定。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_pascal_string:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **store_pascal_string**\ (\ string\: :ref:`String<class_String>`\ ) :ref:`🔗<class_FileAccess_method_store_pascal_string>`
将给定的 :ref:`String<class_String>` 作为一行存储到文件中，使用 Pascal 格式（即同时存储字符串的长度）。文本使用 UTF-8 编码。文件游标的前进量为写入的字节数，取决于 UTF-8 编码后的字节，可能与 :ref:`String.length()<class_String_method_length>` 不同，后者计算的是 UTF-32 码位的数量。如果操作成功则返回 ``true``\ 。
\ **注意：**\ 出错时，文件位置标识符的取值不确定。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_real:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **store_real**\ (\ value\: :ref:`float<class_float>`\ ) :ref:`🔗<class_FileAccess_method_store_real>`
将一个浮点数存储到文件中。文件游标前进 4 个或 8 个字节，取决于当前 Godot 构建所使用的精度。
如果所用的 Godot 构建在编译时使用了 ``precision=single`` 选项（默认），则该方法保存的是 32 位 float。否则如果编译时使用了 ``precision=double`` 选项，则保存的是 64 位 float。如果操作成功则返回 ``true``\ 。
\ **注意：**\ 出错时，文件位置标识符的取值不确定。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_string:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **store_string**\ (\ string\: :ref:`String<class_String>`\ ) :ref:`🔗<class_FileAccess_method_store_string>`
将 ``string`` 存储到文件中，不带换行符（\ ``\n``\ ），文本使用 UTF-8 编码。文件游标的前进量为 UTF-8 编码后的字节数，可能与 :ref:`String.length()<class_String_method_length>` 不同，后者计算的是 UTF-32 码位的数量。如果操作成功则返回 ``true``\ 。
\ **注意：**\ 该方法适用于写入文本文件。字符串以 UTF-8 编码的缓冲区形式存储，不带字符串长度，不以零结尾，加载并非易事。如果你想要在二进制文件中存储便于读取的字符串，请考虑改用 :ref:`store_pascal_string()<class_FileAccess_method_store_pascal_string>`\ 。从文本文件中读取字符串可以使用 ``get_buffer(length).get_string_from_utf8()``\ （前提是知道长度）或 :ref:`get_as_text()<class_FileAccess_method_get_as_text>`\ 。
\ **注意：**\ 出错时，文件位置标识符的取值不确定。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_var:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **store_var**\ (\ value\: :ref:`Variant<class_Variant>`, full_objects\: :ref:`bool<class_bool>` = false\ ) :ref:`🔗<class_FileAccess_method_store_var>`
将任意 Variant 值存储到文件中。如果 ``full_objects`` 为 ``true``\ ，则允许将对象进行编码（可能包含代码）。文件游标的前进量为写入的字节数。如果操作成功则返回 ``true``\ 。
内部使用的编码机制与 :ref:`@GlobalScope.var_to_bytes()<class_@GlobalScope_method_var_to_bytes>` 方法相同，见《\ :doc:`二进制序列化 API <../tutorials/io/binary_serialization_api>` 》文档。
\ **注意：**\ 不是所有属性都会包含在内。只会对设置了 :ref:`@GlobalScope.PROPERTY_USAGE_STORAGE<class_@GlobalScope_constant_PROPERTY_USAGE_STORAGE>` 标志的属性进行序列化。在你的类中覆盖 :ref:`Object._get_property_list()<class_Object_private_method__get_property_list>` 可以为属性添加新的用法标志。你也可以调用 :ref:`Object._get_property_list()<class_Object_private_method__get_property_list>` 查看属性用法的设置情况。可能的用法标志见 :ref:`PropertyUsageFlags<enum_@GlobalScope_PropertyUsageFlags>`\ 。
\ **注意：**\ 出错时，文件位置标识符的取值不确定。
.. |virtual| replace:: :abbr:`virtual (本方法通常需要用户覆盖才能生效。)`
.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)`
.. |const| replace:: :abbr:`const (本方法无副作用，不会修改该实例的任何成员变量。)`
.. |vararg| replace:: :abbr:`vararg (本方法除了能接受在此处描述的参数外，还能够继续接受任意数量的参数。)`
.. |constructor| replace:: :abbr:`constructor (本方法用于构造某个类型。)`
.. |static| replace:: :abbr:`static (调用本方法无需实例，可直接使用类名进行调用。)`
.. |operator| replace:: :abbr:`operator (本方法描述的是使用本类型作为左操作数的有效运算符。)`
.. |bitfield| replace:: :abbr:`BitField (这个值是由下列位标志构成位掩码的整数。)`
.. |void| replace:: :abbr:`void (无返回值。)`
Reference in New Issue View Git Blame Copy Permalink