ConfigFile¶

处理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);

// 1将其保存为一个文件（若文件已存在则会进行覆盖）。
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():
    # Fetch the data for each section.
    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 i3D.Collections.Dictionary();
var config = new ConfigFile();

// 从文件中加载数据。
Error err = config.Load("user://scores.cfg");

// 如果文件没有加载成功，忽略它。
if (err != Error.Ok)
{
    return;
}

// 对所有部分进行迭代。
foreach (String player in config.GetSections())
{
    // Fetch the data for each section.
    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()保存更改。请记住，节和属性名称不能包含空格。空格后的任何内容在保存和加载时都将被忽略。配置文件还可能包含手动编写的注释行，以分号 (;) 开头。这些行在解析文件时将被忽略。请注意，在保存配置文件时，注释将丢失。这对于专用服务器配置文件仍然有用，如果没有明确的用户操作，这些文件通常永远不会被覆盖。

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

方法¶

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

方法说明¶

void clear() 🔗

删除配置的全部内容。

String encode_to_text() const 🔗

获取此配置文件的文本版本（将写入文件的相同文本）。

void erase_section(section: String) 🔗

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

void erase_section_key(section: String, key: String) 🔗

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

PackedStringArray get_section_keys(section: String) const 🔗

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

PackedStringArray get_sections() const 🔗

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

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

返回指定部分和键的当前值。如果部分或键不存在，则该方法返回回退default值。如果未指定default或设置为null，也会引发错误。

bool has_section(section: String) const 🔗

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

bool has_section_key(section: String, key: String) const 🔗

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

Error load(path: String) 🔗

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