ConfigFile

Inherits: Reference < Object

用于处理 INI 样式文件的辅助类。

描述

这个辅助类可以用来在文件系统中使用 INI 风格来格式化存储 Variant 值。存储的值由部分和对应键来识别。

[section]
some_key=42
string_example="Hello World!"
a_vector=Vector3( 1, 0, 2 )

存储的数据可以被保存到文件中，或从文件中解析出来，尽管 ConfigFile 对象也可以直接使用而不需要访问文件系统。

下面的例子展示了如何创建一个简单的 ConfigFile 并将其保存在磁盘上。

# 创建新的 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")

这个例子显示了如何加载上述文件。

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

任何改变 ConfigFile 的操作，如 set_value、clear 或 erase_section，都只改变内存中加载的内容。如果你想把变化写入文件，必须用 save、save_encrypted 或 save_encrypted_pass 保存这些变化。

请记住，部分和属性名称不能包含空格。空格之后的内容在保存和加载时都会被忽略。

配置文件还可以包含以分号开头的手动编写的注释行（;）。这些行在解析文件时将被忽略。请注意，在保存 ConfigFile 时，注释将会丢失。注释对于专用的服务器配置文件仍然很有用，因为如果没有明确的用户操作，这些文件通常不会被覆盖。

注意：给予配置文件扩展名对其格式或行为没有任何影响。根据惯例，这里使用的是 .cfg 扩展名，但任何其他扩展名，如 .ini 也是有效的。由于 .cfg 和 .ini 都不是标准化的，Godot 的 ConfigFile 格式可能与其他程序编写的文件有所不同。

方法

方法说明

• void clear ( )

删除配置的全部内容。

• void erase_section ( String section )

删除指定的部分以及内部的所有键值对。如果该节不存在，则会引发错误。

• void erase_section_key ( String section, String key )

删除部分中的指定键。如果该部分或键不存在，则会引发错误。

• PoolStringArray get_section_keys ( String section ) const

返回指定部分中所有已定义键标识符的数组。如果该部分不存在，则会引发错误并返回一个空数组。

• PoolStringArray get_sections ( ) const

返回所有已定义节标识符的数组。

• Variant get_value ( String section, String key, Variant default=null ) const

返回指定部分和键的当前值。如果节或键不存在，本方法返回后备值default。如果没有指定default或者设置为null，也会引发一个错误。

• bool has_section ( String section ) const

如果指定的部分存在，则返回true。

• bool has_section_key ( String section, String key ) const

如果指定的段键对存在，则返回true。

• Error load ( String path )

加载指定为参数的配置文件。解析文件的内容并将其加载到调用该方法的ConfigFile对象中。

返回Error代码常量之一（成功时返回OK）。

• Error load_encrypted ( String path, PoolByteArray key )

加载指定为参数的加密配置文件，使用提供的key对其解密。解析文件的内容并将其加载到调用该方法的ConfigFile对象中。

返回Error代码常量之一（成功时返回OK）。

• Error load_encrypted_pass ( String path, String password )

加载作为参数的加密配置文件，使用提供的password解密。该文件的内容被解析并加载到调用该方法的 ConfigFile 对象中。

返回Error代码常量之一（成功时返回OK）。

• Error parse ( String data )

将传递的字符串解析为配置文件的内容。该字符串被解析并加载到调用该方法的 ConfigFile 对象中。

返回 Error 常量之一，成功时返回 OK。

• Error save ( String path )

将ConfigFile对象的内容保存到指定为参数的文件中。输出文件使用INI样式的结构。

返回Error代码常量之一（成功时返回OK）。

• Error save_encrypted ( String path, PoolByteArray key )

使用提供的key将ConfigFile对象的内容保存到作为参数指定的AES-256加密文件中。输出文件使用INI样式的结构。

返回Error代码常量之一（成功时返回OK）。

• Error save_encrypted_pass ( String path, String password )

将ConfigFile对象的内容保存到作为参数指定的AES-256加密文件中，使用提供的password进行加密。输出文件使用 INI 风格的结构。

返回 Error 代码常量之一 (成功时返回 OK)。

• void set_value ( String section, String key, Variant value )

为指定章节的指定键赋值。如果节或键不存在，则创建它们。如果指定的键存在，传递一个null的值就会删除指定的键，如果键被删除后，键最终是空的，就会删除节。