:github_url: hide .. _class_ConfigFile: ConfigFile ========== **继承：** :ref:`RefCounted` **<** :ref:`Object` 用于处理 INI 样式文件的辅助类。 .. rst-class:: classref-introduction-group 描述 ---- 该辅助类可用于使用 INI 样式格式在文件系统上存储 :ref:`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()`\ 、\ :ref:`clear()`\ 、\ :ref:`erase_section()` 等修改 ConfigFile 的操作只会改变内存中所加载的内容。如果要将更改写入文件，则必须使用 :ref:`save()`\ 、\ :ref:`save_encrypted()` 或 :ref:`save_encrypted_pass()` 保存更改。 请记住，小节和属性名称不能包含空格。保存和加载时将忽略空格后的任何内容。 ConfigFile 还可以包含以分号（\ ``;``\ ）开头的手动编写的注释行。解析文件时将忽略这些行。请注意，保存 ConfigFile 时注释将丢失。注释对于专用服务器配置文件仍然很有用，如果没有明确的用户操作，这些文件通常永远不会被覆盖。 \ **注意：**\ 为 ConfigFile 指定的文件扩展名对其格式或行为没有任何影响。按照惯例，此处使用 ``.cfg`` 扩展名，但 ``.ini`` 等任何其他扩展名也有效。由于 ``.cfg`` 和 ``.ini`` 都不是标准化的格式，Godot 的 ConfigFile 格式可能与其他程序编写的文件不同。 .. rst-class:: classref-reftable-group 方法 ---- .. table:: :widths: auto +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`clear`\ (\ ) | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`encode_to_text`\ (\ ) |const| | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`erase_section`\ (\ section\: :ref:`String`\ ) | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`erase_section_key`\ (\ section\: :ref:`String`, key\: :ref:`String`\ ) | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedStringArray` | :ref:`get_section_keys`\ (\ section\: :ref:`String`\ ) |const| | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedStringArray` | :ref:`get_sections`\ (\ ) |const| | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`get_value`\ (\ section\: :ref:`String`, key\: :ref:`String`, default\: :ref:`Variant` = null\ ) |const| | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_section`\ (\ section\: :ref:`String`\ ) |const| | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_section_key`\ (\ section\: :ref:`String`, key\: :ref:`String`\ ) |const| | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`load`\ (\ path\: :ref:`String`\ ) | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`load_encrypted`\ (\ path\: :ref:`String`, key\: :ref:`PackedByteArray`\ ) | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`load_encrypted_pass`\ (\ path\: :ref:`String`, password\: :ref:`String`\ ) | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`parse`\ (\ data\: :ref:`String`\ ) | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`save`\ (\ path\: :ref:`String`\ ) | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`save_encrypted`\ (\ path\: :ref:`String`, key\: :ref:`PackedByteArray`\ ) | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`save_encrypted_pass`\ (\ path\: :ref:`String`, password\: :ref:`String`\ ) | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_value`\ (\ section\: :ref:`String`, key\: :ref:`String`, value\: :ref:`Variant`\ ) | +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 方法说明 -------- .. _class_ConfigFile_method_clear: .. rst-class:: classref-method |void| **clear**\ (\ ) :ref:`🔗` 移除配置的全部内容。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_encode_to_text: .. rst-class:: classref-method :ref:`String` **encode_to_text**\ (\ ) |const| :ref:`🔗` 获得该配置文件的文本版本（与写入文件的文本相同）。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_erase_section: .. rst-class:: classref-method |void| **erase_section**\ (\ section\: :ref:`String`\ ) :ref:`🔗` 删除指定小节以及其中的所有键值对。如果该小节不存在，则会引发错误。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_erase_section_key: .. rst-class:: classref-method |void| **erase_section_key**\ (\ section\: :ref:`String`, key\: :ref:`String`\ ) :ref:`🔗` 删除小节中的指定键。如果该小节或键不存在，则会引发错误。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_get_section_keys: .. rst-class:: classref-method :ref:`PackedStringArray` **get_section_keys**\ (\ section\: :ref:`String`\ ) |const| :ref:`🔗` 返回指定小节中所有已定义键标识符的数组。如果该小节不存在，则会引发错误并返回一个空数组。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_get_sections: .. rst-class:: classref-method :ref:`PackedStringArray` **get_sections**\ (\ ) |const| :ref:`🔗` 返回所有已定义小节的标识符的数组。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_get_value: .. rst-class:: classref-method :ref:`Variant` **get_value**\ (\ section\: :ref:`String`, key\: :ref:`String`, default\: :ref:`Variant` = null\ ) |const| :ref:`🔗` 返回指定小节和键的当前值。如果该小节或键不存在，则该方法返回后备值 ``default``\ 。如果未指定 ``default`` 或将其设置为 ``null``\ ，则会引发一个错误。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_has_section: .. rst-class:: classref-method :ref:`bool` **has_section**\ (\ section\: :ref:`String`\ ) |const| :ref:`🔗` 如果指定的小节存在，则返回 ``true``\ 。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_has_section_key: .. rst-class:: classref-method :ref:`bool` **has_section_key**\ (\ section\: :ref:`String`, key\: :ref:`String`\ ) |const| :ref:`🔗` 如果指定的小节-键对存在，则返回 ``true``\ 。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_load: .. rst-class:: classref-method :ref:`Error` **load**\ (\ path\: :ref:`String`\ ) :ref:`🔗` 加载指定为参数的配置文件。解析文件的内容并将其加载到调用该方法的 **ConfigFile** 对象中。 成功时返回 :ref:`@GlobalScope.OK`\ ，操作失败时返回其他 :ref:`Error` 值。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_load_encrypted: .. rst-class:: classref-method :ref:`Error` **load_encrypted**\ (\ path\: :ref:`String`, key\: :ref:`PackedByteArray`\ ) :ref:`🔗` 加载指定为参数的加密配置文件，使用提供的 ``key`` 对其解密。解析文件的内容并将其加载到调用该方法的 **ConfigFile** 对象中。 成功时返回 :ref:`@GlobalScope.OK`\ ，操作失败时返回其他 :ref:`Error` 值。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_load_encrypted_pass: .. rst-class:: classref-method :ref:`Error` **load_encrypted_pass**\ (\ path\: :ref:`String`, password\: :ref:`String`\ ) :ref:`🔗` 加载作为参数的加密配置文件，使用提供的 ``password`` 解密。该文件的内容被解析并加载到调用该方法的 **ConfigFile** 对象中。 成功时返回 :ref:`@GlobalScope.OK`\ ，操作失败时返回其他 :ref:`Error` 值。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_parse: .. rst-class:: classref-method :ref:`Error` **parse**\ (\ data\: :ref:`String`\ ) :ref:`🔗` 将传递的字符串解析为配置文件的内容。该字符串被解析并加载到调用该方法的 ConfigFile 对象中。 成功时返回 :ref:`@GlobalScope.OK`\ ，操作失败时返回其他 :ref:`Error` 值。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_save: .. rst-class:: classref-method :ref:`Error` **save**\ (\ path\: :ref:`String`\ ) :ref:`🔗` 将 **ConfigFile** 对象的内容保存到指定为参数的文件中。输出文件使用 INI 样式的结构。 成功时返回 :ref:`@GlobalScope.OK`\ ，操作失败时返回其他 :ref:`Error` 值。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_save_encrypted: .. rst-class:: classref-method :ref:`Error` **save_encrypted**\ (\ path\: :ref:`String`, key\: :ref:`PackedByteArray`\ ) :ref:`🔗` 使用提供的 ``key`` 将 **ConfigFile** 对象的内容保存到作为参数指定的 AES-256 加密文件中。输出文件使用 INI 样式的结构。 成功时返回 :ref:`@GlobalScope.OK`\ ，操作失败时返回其他 :ref:`Error` 值。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_save_encrypted_pass: .. rst-class:: classref-method :ref:`Error` **save_encrypted_pass**\ (\ path\: :ref:`String`, password\: :ref:`String`\ ) :ref:`🔗` 将 **ConfigFile** 对象的内容保存到作为参数指定的 AES-256 加密文件中，使用提供的 ``password`` 进行加密。输出文件使用 INI 风格的结构。 成功时返回 :ref:`@GlobalScope.OK`\ ，操作失败时返回其他 :ref:`Error` 值。 .. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_set_value: .. rst-class:: classref-method |void| **set_value**\ (\ section\: :ref:`String`, key\: :ref:`String`, value\: :ref:`Variant`\ ) :ref:`🔗` 为指定小节的指定键赋值。如果小节或键不存在，则创建它们。如果指定的键存在，传递 ``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 (无返回值。)`