godotengine/godot-docs-l10n
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs-l10n.git synced 2026-01-04 10:09:56 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
36d0439ca5be178d7e6b4f9b6bffbcf4f90209f5
godot-docs-l10n/classes/zh_CN/class_fileaccess.rst

1254 lines
76 KiB
ReStructuredText
Raw 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
.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/FileAccess.xml.
.. _class_FileAccess:
FileAccess
==========
**继承：** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`
提供用于文件读写操作的方法。
.. rst-class:: classref-introduction-group
描述
----
这个类可以用于在用户设备的文件系统中永久存储数据，也可以从中读取数据。适用于存储游戏存档数据或玩家配置文件。
下面是一个关于如何写入和读取文件的示例：
.. 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;
}
在上面的例子中，文件将被保存在\ :doc:`数据路径 <../tutorials/io/data_paths>`\ 文件中指定的用户数据文件夹中。
\ **FileAccess** 会在释放时关闭，超出作用于、赋值为 ``null`` 等情况都会导致释放。可以使用 :ref:`close<class_FileAccess_method_close>` 在此之前显式关闭。在 C# 中，引用必须手动释放，可以通过 ``using`` 语句或直接调用 ``Dispose`` 方法来完成。
\ **注意：**\ 要在导出后访问项目资源，建议使用 :ref:`ResourceLoader<class_ResourceLoader>` 而不是 **FileAccess**\ ，因为有些文件已被转换为特定于引擎的格式，并且它们的原始源文件可能并不存在于导出的 PCK 包中。
\ **注意：**\ 只有当进程“正常”退出时（例如通过单击窗口管理器的关闭按钮或按 **Alt + F4**\ ），文件才会自动关闭。如果在项目运行时按 **F8** 停止项目执行，则不会关闭文件，因为游戏进程将被杀死。可以通过定期调用 :ref:`flush<class_FileAccess_method_flush>` 来解决这个问题。
.. rst-class:: classref-introduction-group
教程
----
- :doc:`文件系统 <../tutorials/scripting/filesystem>`
- :doc:`运行时文件加载与保存 <../tutorials/io/runtime_file_loading_and_saving>`
- `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:`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:`String<class_String>` | :ref:`get_as_text<class_FileAccess_method_get_as_text>`\ (\ skip_cr\: :ref:`bool<class_bool>` = false\ ) |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_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:`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| |
+-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |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>`\ ) |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:`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_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| |
+-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`store_8<class_FileAccess_method_store_8>`\ (\ value\: :ref:`int<class_int>`\ ) |
+-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`store_16<class_FileAccess_method_store_16>`\ (\ value\: :ref:`int<class_int>`\ ) |
+-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`store_32<class_FileAccess_method_store_32>`\ (\ value\: :ref:`int<class_int>`\ ) |
+-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`store_64<class_FileAccess_method_store_64>`\ (\ value\: :ref:`int<class_int>`\ ) |
+-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`store_buffer<class_FileAccess_method_store_buffer>`\ (\ buffer\: :ref:`PackedByteArray<class_PackedByteArray>`\ ) |
+-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`store_csv_line<class_FileAccess_method_store_csv_line>`\ (\ values\: :ref:`PackedStringArray<class_PackedStringArray>`, delim\: :ref:`String<class_String>` = ","\ ) |
+-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`store_double<class_FileAccess_method_store_double>`\ (\ value\: :ref:`float<class_float>`\ ) |
+-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`store_float<class_FileAccess_method_store_float>`\ (\ value\: :ref:`float<class_float>`\ ) |
+-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`store_line<class_FileAccess_method_store_line>`\ (\ line\: :ref:`String<class_String>`\ ) |
+-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`store_pascal_string<class_FileAccess_method_store_pascal_string>`\ (\ string\: :ref:`String<class_String>`\ ) |
+-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`store_real<class_FileAccess_method_store_real>`\ (\ value\: :ref:`float<class_float>`\ ) |
+-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`store_string<class_FileAccess_method_store_string>`\ (\ string\: :ref:`String<class_String>`\ ) |
+-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :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``
打开文件进行写操作。如果文件不存在则会创建该文件，如果存在则会截断。
\ **注意：**\ 创建文件必须在已有目录中执行。如果要递归创建文件路径中的目录，见 :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``
打开文件进行读写操作。如果文件不存在则会创建该文件，如果存在则会截断。光标位于文件的开头。
\ **注意：**\ 创建文件必须在已有目录中执行。如果要递归创建文件路径中的目录，见 :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>` 只与文件格式有关，与 CPU 类型无关。CPU 字节序不会影响写入文件的默认字节序。
\ **注意：**\ 每当打开文件时，该选项总是被重置为 ``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_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 位。请参阅 :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 位。请参阅 :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 位。请参阅\ :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 位。请参阅 :ref:`store_64<class_FileAccess_method_store_64>`\ ，以获取有关可以通过这种方式存储和检索哪些值的详细信息。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_get_as_text:
.. rst-class:: classref-method
:ref:`String<class_String>` **get_as_text**\ (\ skip_cr\: :ref:`bool<class_bool>` = false\ ) |const| :ref:`🔗<class_FileAccess_method_get_as_text>`
以 :ref:`String<class_String>` 形式返回整个文件。文本会按照 UTF-8 编码解析。
如果 ``skip_cr`` 为 ``true``\ ，解析 UTF-8 时会忽略回车符（\ ``\r``\ ，CR），因此只使用换行符（\ ``\n``\ ，LF）表示新一行的开始（Unix 规范）。
.. 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>` 返回。
.. 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 位作为浮点数返回。
.. 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_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 位作为浮点数返回。
.. 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>`
如果文件 ``hidden`` 属性已设置，则返回 ``true``\ 。
\ **注意：**\ 该方法在 iOS、BSD、macOS 和 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>` 字符串。
将按照 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>`
返回文件光标的位置。
.. 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>`
如果文件 ``read only`` 属性已设置，则返回 ``true``\ 。
\ **注意：**\ 此方法在 iOS、BSD、macOS 和 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>`
将文件中接下来的若干位以浮点数形式返回。
.. 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_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>`
返回文件的 UNIX 权限。
\ **注意：**\ 该方法在 iOS、Linux/BSD 和 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>` 方法相同的解码机制。
\ **警告：**\ 反序列化得到的对象可能包含被执行的代码。如果序列化的对象来自不受信任的来源，请不要使用这个选项，以避免潜在的安全威胁，如远程代码执行。
.. 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>`\ ) |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_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>`
将文件的读/写光标改变到指定的位置（从文件开始的字节数）。
.. 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>`
将文件的读/写光标改变到指定的位置（从文件的末端算起，以字节为单位）。
\ **注意：**\ 这是一个偏移量，所以你应该使用负数，否则光标会在文件的末端。
.. 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
|void| **store_8**\ (\ value\: :ref:`int<class_int>`\ ) :ref:`🔗<class_FileAccess_method_store_8>`
将一个整数以 8 位形式存储在文件中。
\ **注意：**\ ``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
|void| **store_16**\ (\ value\: :ref:`int<class_int>`\ ) :ref:`🔗<class_FileAccess_method_store_16>`
将一个整数以 16 位形式存储在文件中。
\ **注意：**\ ``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
|void| **store_32**\ (\ value\: :ref:`int<class_int>`\ ) :ref:`🔗<class_FileAccess_method_store_32>`
将一个整数以 32 位形式存储在文件中。
\ **注意：**\ ``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
|void| **store_64**\ (\ value\: :ref:`int<class_int>`\ ) :ref:`🔗<class_FileAccess_method_store_64>`
将一个整数以 64 位形式存储在文件中。
\ **注意：**\ ``value`` 必须位于 ``[-2^63, 2^63 - 1]`` 的区间内（即有效的 :ref:`int<class_int>` 值）。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_buffer:
.. rst-class:: classref-method
|void| **store_buffer**\ (\ buffer\: :ref:`PackedByteArray<class_PackedByteArray>`\ ) :ref:`🔗<class_FileAccess_method_store_buffer>`
在文件中存储给定的字节数组。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_csv_line:
.. rst-class:: classref-method
|void| **store_csv_line**\ (\ values\: :ref:`PackedStringArray<class_PackedStringArray>`, delim\: :ref:`String<class_String>` = ","\ ) :ref:`🔗<class_FileAccess_method_store_csv_line>`
将给定的 :ref:`PackedStringArray<class_PackedStringArray>` 作为 CSV（逗号分隔值）格式的行存储在文件中。你可以传递不同的分隔符 ``delim`` 以使用默认 ``","``\ （逗号）以外的其他分隔符。此分隔符的长度必须为一个字符。
将使用 UTF-8 编码文本。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_double:
.. rst-class:: classref-method
|void| **store_double**\ (\ value\: :ref:`float<class_float>`\ ) :ref:`🔗<class_FileAccess_method_store_double>`
将一个浮点数以 64 位形式存储在文件中。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_float:
.. rst-class:: classref-method
|void| **store_float**\ (\ value\: :ref:`float<class_float>`\ ) :ref:`🔗<class_FileAccess_method_store_float>`
将一个浮点数以 32 位形式存储在文件中。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_line:
.. rst-class:: classref-method
|void| **store_line**\ (\ line\: :ref:`String<class_String>`\ ) :ref:`🔗<class_FileAccess_method_store_line>`
将 ``line`` 附加到文件末尾，并在后面加上一个换行符（\ ``\n``\ ），将使用 UTF-8 编码文本。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_pascal_string:
.. rst-class:: classref-method
|void| **store_pascal_string**\ (\ string\: :ref:`String<class_String>`\ ) :ref:`🔗<class_FileAccess_method_store_pascal_string>`
将给定的 :ref:`String<class_String>` 以 Pascal 格式存储在文件中（即同时存储字符串的长度）。
将使用 UTF-8 编码文本。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_real:
.. rst-class:: classref-method
|void| **store_real**\ (\ value\: :ref:`float<class_float>`\ ) :ref:`🔗<class_FileAccess_method_store_real>`
将浮点数存储在文件中。
.. rst-class:: classref-item-separator
----
.. _class_FileAccess_method_store_string:
.. rst-class:: classref-method
|void| **store_string**\ (\ string\: :ref:`String<class_String>`\ ) :ref:`🔗<class_FileAccess_method_store_string>`
将 ``string`` 追加到文件中，不带换行，且将文本编码为 UTF-8。
\ **注意：**\ 本方法是用来写入文本文件的。字符串会被存储为 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
|void| **store_var**\ (\ value\: :ref:`Variant<class_Variant>`, full_objects\: :ref:`bool<class_bool>` = false\ ) :ref:`🔗<class_FileAccess_method_store_var>`
在文件中存储任何 Variant 值。如果 ``full_objects`` 为 ``true``\ ，则允许编码对象（并且可能包含代码）。
在内部，这使用与 :ref:`@GlobalScope.var_to_bytes<class_@GlobalScope_method_var_to_bytes>` 方法相同的编码机制。
\ **注意：**\ 并非所有属性都包括在内。只有配置了 :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 (本方法通常需要用户覆盖才能生效。)`
.. |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