ConfigFile

ConfigFile

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

描述

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

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

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

以下示例显示了如何创建一个简单的 ConfigFile 并将其保存在磁盘上：

GDScriptC#

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

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

GDScriptC#

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