Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

ConfigFile¶

继承： RefCounted < Object

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

描述¶

该辅助类可用于使用 INI 样式格式在文件系统上存储 Variant 值。存储的值由一个小节和一个键标识：

[section]
some_key=42
string_example="Hello World3D!"
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")

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

该示例展示了如何加载上面的文件：

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

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;
}

任何改变 ConfigFile 的操作，例如 set_value、clear、或 erase_section，只会改变加载到内存中的内容。如果要将更改写入文件，则必须使用 save、save_encrypted、或 save_encrypted_pass 保存更改。

请记住，小节和属性名称不能包含空格。保存和加载时将忽略空格后的任何内容。

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

注意：为 ConfigFile 指定的文件扩展名对其格式或行为没有任何影响。按照惯例，此处使用 .cfg 扩展名，但 .ini 等任何其他扩展名也有效。由于 .cfg 和 .ini 都不是标准化的格式，Godot 的 ConfigFile 格式可能与其他程序编写的文件不同。

方法¶

void	clear ( )
String	encode_to_text ( ) const
void	erase_section ( String section )
void	erase_section_key ( String section, String key )
PackedStringArray	get_section_keys ( String section ) const
PackedStringArray	get_sections ( ) const
Variant	get_value ( String section, String key, Variant default=null ) const
bool	has_section ( String section ) const
bool	has_section_key ( String section, String key ) const
Error	load ( String path )
Error	load_encrypted ( String path, PackedByteArray key )
Error	load_encrypted_pass ( String path, String password )
Error	parse ( String data )
Error	save ( String path )
Error	save_encrypted ( String path, PackedByteArray key )
Error	save_encrypted_pass ( String path, String password )
void	set_value ( String section, String key, Variant value )

方法说明¶

void clear ( )

移除配置的全部内容。

String encode_to_text ( ) const

获得该配置文件的文本版本（与写入文件的文本相同）。

void erase_section ( String section )

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

void erase_section_key ( String section, String key )

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

PackedStringArray get_section_keys ( String section ) const

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

PackedStringArray 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 对象中。