mirror of
https://github.com/godotengine/godot-docs-l10n.git
synced 2025-12-31 09:49:22 +03:00
396 lines
21 KiB
ReStructuredText
396 lines
21 KiB
ReStructuredText
:github_url: hide
|
||
|
||
.. _class_ConfigFile:
|
||
|
||
ConfigFile
|
||
==========
|
||
|
||
**继承：** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`
|
||
|
||
用于处理 INI 样式文件的辅助类。
|
||
|
||
.. rst-class:: classref-introduction-group
|
||
|
||
描述
|
||
----
|
||
|
||
该辅助类可用于使用 INI 样式格式在文件系统上存储 :ref:`Variant<class_Variant>` 值。存储的值由一个小节和一个键标识：
|
||
|
||
.. code:: text
|
||
|
||
[section]
|
||
some_key=42
|
||
string_example="Hello World3D!"
|
||
a_vector=Vector3(1, 0, 2)
|
||
|
||
存储的数据可以被保存到文件中或从文件中解析出来，尽管 ConfigFile 对象也可以直接使用而无需访问文件系统。
|
||
|
||
以下示例显示了如何创建一个简单的 **ConfigFile** 并将其保存在磁盘上：
|
||
|
||
|
||
.. tabs::
|
||
|
||
.. code-tab:: gdscript
|
||
|
||
# 创建新的 ConfigFile 对象。
|
||
var config = ConfigFile.new()
|
||
|
||
# 存储一些值。
|
||
config.set_value("Player1", "player_name", "Steve")
|
||
config.set_value("Player1", "best_score", 10)
|
||
config.set_value("Player2", "player_name", "V3geta")
|
||
config.set_value("Player2", "best_score", 9001)
|
||
|
||
# 将其保存到文件中（如果已存在则覆盖）。
|
||
config.save("user://scores.cfg")
|
||
|
||
.. code-tab:: csharp
|
||
|
||
// 创建新的 ConfigFile 对象。
|
||
var config = new ConfigFile();
|
||
|
||
// 存储一些值。
|
||
config.SetValue("Player1", "player_name", "Steve");
|
||
config.SetValue("Player1", "best_score", 10);
|
||
config.SetValue("Player2", "player_name", "V3geta");
|
||
config.SetValue("Player2", "best_score", 9001);
|
||
|
||
// 将其保存到文件中（如果已存在则覆盖）。
|
||
config.Save("user://scores.cfg");
|
||
|
||
|
||
|
||
该示例展示了如何加载上面的文件：
|
||
|
||
|
||
.. tabs::
|
||
|
||
.. code-tab:: gdscript
|
||
|
||
var score_data = {}
|
||
var config = ConfigFile.new()
|
||
|
||
# 从文件加载数据。
|
||
var err = config.load("user://scores.cfg")
|
||
|
||
# 如果文件没有加载，忽略它。
|
||
if err != OK:
|
||
return
|
||
|
||
# 迭代所有小节。
|
||
for player in config.get_sections():
|
||
# 获取每个小节的数据。
|
||
var player_name = config.get_value(player, "player_name")
|
||
var player_score = config.get_value(player, "best_score")
|
||
score_data[player_name] = player_score
|
||
|
||
.. code-tab:: csharp
|
||
|
||
var score_data = new Godot.Collections.Dictionary();
|
||
var config = new ConfigFile();
|
||
|
||
// 从文件加载数据。
|
||
Error err = config.Load("user://scores.cfg");
|
||
|
||
// 如果文件没有加载，忽略它。
|
||
if (err != Error.Ok)
|
||
{
|
||
return;
|
||
}
|
||
|
||
// 迭代所有小节。
|
||
foreach (String player in config.GetSections())
|
||
{
|
||
// 获取每个小节的数据。
|
||
var player_name = (String)config.GetValue(player, "player_name");
|
||
var player_score = (int)config.GetValue(player, "best_score");
|
||
score_data[player_name] = player_score;
|
||
}
|
||
|
||
|
||
|
||
\ :ref:`set_value()<class_ConfigFile_method_set_value>`\ 、\ :ref:`clear()<class_ConfigFile_method_clear>`\ 、\ :ref:`erase_section()<class_ConfigFile_method_erase_section>` 等修改 ConfigFile 的操作只会改变内存中所加载的内容。如果要将更改写入文件，则必须使用 :ref:`save()<class_ConfigFile_method_save>`\ 、\ :ref:`save_encrypted()<class_ConfigFile_method_save_encrypted>` 或 :ref:`save_encrypted_pass()<class_ConfigFile_method_save_encrypted_pass>` 保存更改。
|
||
|
||
请记住，小节和属性名称不能包含空格。保存和加载时将忽略空格后的任何内容。
|
||
|
||
ConfigFile 还可以包含以分号（\ ``;``\ ）开头的手动编写的注释行。解析文件时将忽略这些行。请注意，保存 ConfigFile 时注释将丢失。注释对于专用服务器配置文件仍然很有用，如果没有明确的用户操作，这些文件通常永远不会被覆盖。
|
||
|
||
\ **注意：**\ 为 ConfigFile 指定的文件扩展名对其格式或行为没有任何影响。按照惯例，此处使用 ``.cfg`` 扩展名，但 ``.ini`` 等任何其他扩展名也有效。由于 ``.cfg`` 和 ``.ini`` 都不是标准化的格式，Godot 的 ConfigFile 格式可能与其他程序编写的文件不同。
|
||
|
||
.. rst-class:: classref-reftable-group
|
||
|
||
方法
|
||
----
|
||
|
||
.. table::
|
||
:widths: auto
|
||
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| |void| | :ref:`clear<class_ConfigFile_method_clear>`\ (\ ) |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`String<class_String>` | :ref:`encode_to_text<class_ConfigFile_method_encode_to_text>`\ (\ ) |const| |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| |void| | :ref:`erase_section<class_ConfigFile_method_erase_section>`\ (\ section\: :ref:`String<class_String>`\ ) |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| |void| | :ref:`erase_section_key<class_ConfigFile_method_erase_section_key>`\ (\ section\: :ref:`String<class_String>`, key\: :ref:`String<class_String>`\ ) |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`PackedStringArray<class_PackedStringArray>` | :ref:`get_section_keys<class_ConfigFile_method_get_section_keys>`\ (\ section\: :ref:`String<class_String>`\ ) |const| |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`PackedStringArray<class_PackedStringArray>` | :ref:`get_sections<class_ConfigFile_method_get_sections>`\ (\ ) |const| |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`Variant<class_Variant>` | :ref:`get_value<class_ConfigFile_method_get_value>`\ (\ section\: :ref:`String<class_String>`, key\: :ref:`String<class_String>`, default\: :ref:`Variant<class_Variant>` = null\ ) |const| |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`bool<class_bool>` | :ref:`has_section<class_ConfigFile_method_has_section>`\ (\ section\: :ref:`String<class_String>`\ ) |const| |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`bool<class_bool>` | :ref:`has_section_key<class_ConfigFile_method_has_section_key>`\ (\ section\: :ref:`String<class_String>`, key\: :ref:`String<class_String>`\ ) |const| |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`load<class_ConfigFile_method_load>`\ (\ path\: :ref:`String<class_String>`\ ) |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`load_encrypted<class_ConfigFile_method_load_encrypted>`\ (\ path\: :ref:`String<class_String>`, key\: :ref:`PackedByteArray<class_PackedByteArray>`\ ) |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`load_encrypted_pass<class_ConfigFile_method_load_encrypted_pass>`\ (\ path\: :ref:`String<class_String>`, password\: :ref:`String<class_String>`\ ) |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`parse<class_ConfigFile_method_parse>`\ (\ data\: :ref:`String<class_String>`\ ) |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`save<class_ConfigFile_method_save>`\ (\ path\: :ref:`String<class_String>`\ ) |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`save_encrypted<class_ConfigFile_method_save_encrypted>`\ (\ path\: :ref:`String<class_String>`, key\: :ref:`PackedByteArray<class_PackedByteArray>`\ ) |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`save_encrypted_pass<class_ConfigFile_method_save_encrypted_pass>`\ (\ path\: :ref:`String<class_String>`, password\: :ref:`String<class_String>`\ ) |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| |void| | :ref:`set_value<class_ConfigFile_method_set_value>`\ (\ section\: :ref:`String<class_String>`, key\: :ref:`String<class_String>`, value\: :ref:`Variant<class_Variant>`\ ) |
|
||
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
|
||
.. rst-class:: classref-section-separator
|
||
|
||
----
|
||
|
||
.. rst-class:: classref-descriptions-group
|
||
|
||
方法说明
|
||
--------
|
||
|
||
.. _class_ConfigFile_method_clear:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
|void| **clear**\ (\ ) :ref:`🔗<class_ConfigFile_method_clear>`
|
||
|
||
移除配置的全部内容。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_encode_to_text:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`String<class_String>` **encode_to_text**\ (\ ) |const| :ref:`🔗<class_ConfigFile_method_encode_to_text>`
|
||
|
||
获得该配置文件的文本版本（与写入文件的文本相同）。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_erase_section:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
|void| **erase_section**\ (\ section\: :ref:`String<class_String>`\ ) :ref:`🔗<class_ConfigFile_method_erase_section>`
|
||
|
||
删除指定小节以及其中的所有键值对。如果该小节不存在，则会引发错误。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_erase_section_key:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
|void| **erase_section_key**\ (\ section\: :ref:`String<class_String>`, key\: :ref:`String<class_String>`\ ) :ref:`🔗<class_ConfigFile_method_erase_section_key>`
|
||
|
||
删除小节中的指定键。如果该小节或键不存在，则会引发错误。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_get_section_keys:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`PackedStringArray<class_PackedStringArray>` **get_section_keys**\ (\ section\: :ref:`String<class_String>`\ ) |const| :ref:`🔗<class_ConfigFile_method_get_section_keys>`
|
||
|
||
返回指定小节中所有已定义键标识符的数组。如果该小节不存在，则会引发错误并返回一个空数组。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_get_sections:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`PackedStringArray<class_PackedStringArray>` **get_sections**\ (\ ) |const| :ref:`🔗<class_ConfigFile_method_get_sections>`
|
||
|
||
返回所有已定义小节的标识符的数组。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_get_value:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`Variant<class_Variant>` **get_value**\ (\ section\: :ref:`String<class_String>`, key\: :ref:`String<class_String>`, default\: :ref:`Variant<class_Variant>` = null\ ) |const| :ref:`🔗<class_ConfigFile_method_get_value>`
|
||
|
||
返回指定小节和键的当前值。如果该小节或键不存在，则该方法返回后备值 ``default``\ 。如果未指定 ``default`` 或将其设置为 ``null``\ ，则会引发一个错误。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_has_section:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`bool<class_bool>` **has_section**\ (\ section\: :ref:`String<class_String>`\ ) |const| :ref:`🔗<class_ConfigFile_method_has_section>`
|
||
|
||
如果指定的小节存在，则返回 ``true``\ 。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_has_section_key:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`bool<class_bool>` **has_section_key**\ (\ section\: :ref:`String<class_String>`, key\: :ref:`String<class_String>`\ ) |const| :ref:`🔗<class_ConfigFile_method_has_section_key>`
|
||
|
||
如果指定的小节-键对存在，则返回 ``true``\ 。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_load:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`Error<enum_@GlobalScope_Error>` **load**\ (\ path\: :ref:`String<class_String>`\ ) :ref:`🔗<class_ConfigFile_method_load>`
|
||
|
||
加载指定为参数的配置文件。解析文件的内容并将其加载到调用该方法的 **ConfigFile** 对象中。
|
||
|
||
成功时返回 :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>`\ ，操作失败时返回其他 :ref:`Error<enum_@GlobalScope_Error>` 值。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_load_encrypted:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`Error<enum_@GlobalScope_Error>` **load_encrypted**\ (\ path\: :ref:`String<class_String>`, key\: :ref:`PackedByteArray<class_PackedByteArray>`\ ) :ref:`🔗<class_ConfigFile_method_load_encrypted>`
|
||
|
||
加载指定为参数的加密配置文件，使用提供的 ``key`` 对其解密。解析文件的内容并将其加载到调用该方法的 **ConfigFile** 对象中。
|
||
|
||
成功时返回 :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>`\ ，操作失败时返回其他 :ref:`Error<enum_@GlobalScope_Error>` 值。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_load_encrypted_pass:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`Error<enum_@GlobalScope_Error>` **load_encrypted_pass**\ (\ path\: :ref:`String<class_String>`, password\: :ref:`String<class_String>`\ ) :ref:`🔗<class_ConfigFile_method_load_encrypted_pass>`
|
||
|
||
加载作为参数的加密配置文件，使用提供的 ``password`` 解密。该文件的内容被解析并加载到调用该方法的 **ConfigFile** 对象中。
|
||
|
||
成功时返回 :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>`\ ，操作失败时返回其他 :ref:`Error<enum_@GlobalScope_Error>` 值。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_parse:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`Error<enum_@GlobalScope_Error>` **parse**\ (\ data\: :ref:`String<class_String>`\ ) :ref:`🔗<class_ConfigFile_method_parse>`
|
||
|
||
将传递的字符串解析为配置文件的内容。该字符串被解析并加载到调用该方法的 ConfigFile 对象中。
|
||
|
||
成功时返回 :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>`\ ，操作失败时返回其他 :ref:`Error<enum_@GlobalScope_Error>` 值。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_save:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`Error<enum_@GlobalScope_Error>` **save**\ (\ path\: :ref:`String<class_String>`\ ) :ref:`🔗<class_ConfigFile_method_save>`
|
||
|
||
将 **ConfigFile** 对象的内容保存到指定为参数的文件中。输出文件使用 INI 样式的结构。
|
||
|
||
成功时返回 :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>`\ ，操作失败时返回其他 :ref:`Error<enum_@GlobalScope_Error>` 值。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_save_encrypted:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`Error<enum_@GlobalScope_Error>` **save_encrypted**\ (\ path\: :ref:`String<class_String>`, key\: :ref:`PackedByteArray<class_PackedByteArray>`\ ) :ref:`🔗<class_ConfigFile_method_save_encrypted>`
|
||
|
||
使用提供的 ``key`` 将 **ConfigFile** 对象的内容保存到作为参数指定的 AES-256 加密文件中。输出文件使用 INI 样式的结构。
|
||
|
||
成功时返回 :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>`\ ，操作失败时返回其他 :ref:`Error<enum_@GlobalScope_Error>` 值。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_save_encrypted_pass:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`Error<enum_@GlobalScope_Error>` **save_encrypted_pass**\ (\ path\: :ref:`String<class_String>`, password\: :ref:`String<class_String>`\ ) :ref:`🔗<class_ConfigFile_method_save_encrypted_pass>`
|
||
|
||
将 **ConfigFile** 对象的内容保存到作为参数指定的 AES-256 加密文件中，使用提供的 ``password`` 进行加密。输出文件使用 INI 风格的结构。
|
||
|
||
成功时返回 :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>`\ ，操作失败时返回其他 :ref:`Error<enum_@GlobalScope_Error>` 值。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ConfigFile_method_set_value:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
|void| **set_value**\ (\ section\: :ref:`String<class_String>`, key\: :ref:`String<class_String>`, value\: :ref:`Variant<class_Variant>`\ ) :ref:`🔗<class_ConfigFile_method_set_value>`
|
||
|
||
为指定小节的指定键赋值。如果小节或键不存在，则创建它们。如果指定的键存在，传递 ``null`` 值就会移除指定的键，如果键被移除后，小节最终是空的，就会移除小节。
|
||
|
||
.. |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 (无返回值。)`
|