Dictionary¶

保存键值对的内置数据结构。

描述¶

字典是包含由唯一键引用的值的关联容器。字典将在添加新条目时保留插入顺序。在其他编程语言中，这种数据结构通常被称为哈希映射或关联数组。

您可以通过在花括号{}内放置key： value对的逗号分隔列表来定义字典。

创建字典：

var my_dict = {} # 创建一个空字典.

var dict_variable_key = "Another key name"
var dict_variable_value = "value2"
var another_dict = {
    "Some key name": "value1",
    dict_variable_key: dict_variable_value,
}

var points_dict = {"White": 50, "Yellow": 75, "Orange": 100}

# 备选的 Lua 风格语法。
# 键名无需加引号，但仅字符串常量可作为键名使用。
# 此外，键名必须以字母或下划线开头。
# 此处的 `some_key` 是字符串字面量，而非变量！

another_dict = {
    some_key = 42,
}

var myDict = new i3D.Collections.Dictionary(); // Creates an empty dictionary.
var pointsDict = new i3D.Collections.Dictionary
{
    {"White", 50},
    {"Yellow", 75},
    {"Orange", 100}
};

你可以通过引用字典对应的键来访问其值。在上述示例中， points_dict["White"] ``会返回 ``50。你也可以写成 points_dict.White，这两种写法是等效的。但是，如果你访问字典时使用的键并非固定字符串（例如是数字或变量），则必须使用方括号语法.

@export_enum("White", "Yellow", "Orange") var my_color: String
var points_dict = {"White": 50, "Yellow": 75, "Orange": 100}
func _ready():
    # 此处无法使用点语法，因为 `my_color` 是一个变量.
    var points = points_dict[my_color]

[Export(PropertyHint.Enum, "White,Yellow,Orange")]
public string MyColor { get; set; }
private i3D.Collections.Dictionary _pointsDict = new i3D.Collections.Dictionary
{
    {"White", 50},
    {"Yellow", 75},
    {"Orange", 100}
};

public override void _Ready()
{
    int points = (int)_pointsDict[MyColor];
}

在上述代码中， points 会被赋值为与 my_color 中所选对应颜色相关联的值.

字典可以包含更复杂的数据：

var my_dict = {
    "First Array": [1, 2, 3, 4] # Assigns an Array to a String key.
}

var myDict = new i3D.Collections.Dictionary
{
    {"First Array", new i3D.Collections.Array{1, 2, 3, 4}}
};

要向已有的字典中添加键，可按访问已有键的方式操作并为其赋值：:

var points_dict = {"White": 50, "Yellow": 75, "Orange": 100}
points_dict["Blue"] = 150 # 添加 “Blue” 作为键，并为其赋值 150.

var pointsDict = new i3D.Collections.Dictionary
{
    {"White", 50},
    {"Yellow", 75},
    {"Orange", 100}
};
pointsDict["Blue"] = 150; // 添加 “Blue” 作为键，并为其赋值 150.

最后，字典中可以在同一个字典里包含不同类型的键和值:

# 这是一个有效的字典.
# 要访问下方的字符串 "Nested value"，可以使用 `my_dict.sub_dict.sub_key` or `my_dict["sub_dict"]["sub_key"]`.
# 可根据需求混合搭配使用不同的索引风格.
var my_dict = {
    "String Key": 5,
    4: [1, 2, 3],
    7: "Hello",
    "sub_dict": {"sub_key": "Nested value"},
}

// 这是一个有效的字典。
// 要访问下方的字符串 "Nested value"，可使用 `((i3D.Collections.Dictionary)myDict["sub_dict"])["sub_key"]`.
var myDict = new i3D.Collections.Dictionary {
    {"String Key", 5},
    {4, new i3D.Collections.Array{1,2,3}},
    {7, "Hello"},
    {"sub_dict", new i3D.Collections.Dictionary{{"sub_key", "Nested value"}}}
};

字典的键可以使用for关键字进行迭代：

var groceries = {"Orange": 20, "Apple": 2, "Banana": 4}
for fruit in groceries:
    var amount = groceries[fruit]

var groceries = new i3D.Collections.Dictionary{{"Orange", 20}, {"Apple", 2}, {"Banana", 4}};
foreach (var (fruit, amount) in groceries)
{
    //  `fruit` 是键， `amount` 是值.
}

注意：字典总是通过引用传递。要获得可以独立于原始字典进行修改的字典副本，请使用duplicate()。

注意：不支持在迭代字典时擦除元素，这将导致不可预测的行为。

构造函数¶

Dictionary	Dictionary()
Dictionary	Dictionary(base: Dictionary, key_type: int, key_class_name: StringName, key_script: Variant, value_type: int, value_class_name: StringName, value_script: Variant)
Dictionary	Dictionary(from: Dictionary)

方法¶

void	assign(dictionary: Dictionary)
void	clear()
Dictionary	duplicate(deep: bool = false) const
bool	erase(key: Variant)
Variant	find_key(value: Variant) const
Variant	get(key: Variant, default: Variant = null) const
Variant	get_or_add(key: Variant, default: Variant = null)
int	get_typed_key_builtin() const
StringName	get_typed_key_class_name() const
Variant	get_typed_key_script() const
int	get_typed_value_builtin() const
StringName	get_typed_value_class_name() const
Variant	get_typed_value_script() const
bool	has(key: Variant) const
bool	has_all(keys: Array) const
int	hash() const
bool	is_empty() const
bool	is_read_only() const
bool	is_same_typed(dictionary: Dictionary) const
bool	is_same_typed_key(dictionary: Dictionary) const
bool	is_same_typed_value(dictionary: Dictionary) const
bool	is_typed() const
bool	is_typed_key() const
bool	is_typed_value() const
Array	keys() const
void	make_read_only()
void	merge(dictionary: Dictionary, overwrite: bool = false)
Dictionary	merged(dictionary: Dictionary, overwrite: bool = false) const
bool	recursive_equal(dictionary: Dictionary, recursion_count: int) const
bool	set(key: Variant, value: Variant)
int	size() const
void	sort()
Array	values() const

运算符¶

bool	operator !=(right: Dictionary)
bool	operator ==(right: Dictionary)
Variant	operator [](key: Variant)

构造函数说明¶

Dictionary Dictionary() 🔗

构造一个空的Dictionary。

Dictionary Dictionary(base: Dictionary, key_type: int, key_class_name: StringName, key_script: Variant, value_type: int, value_class_name: StringName, value_script: Variant)

从base字典创建类型化字典。类型化字典只能包含给定类型或从给定类继承的键和值，如此构造函数的参数所述。

Dictionary Dictionary(from: Dictionary)

返回与from相同的字典。如果您需要字典的副本，请使用duplicate()。

方法说明¶

void assign(dictionary: Dictionary) 🔗

将另一个dictionary的元素分配到字典中。调整字典大小以匹配dictionary。如果输入字典，则执行类型转换。

void clear() 🔗

清除字典，从中删除所有条目。

Dictionary duplicate(deep: bool = false) const 🔗

创建并返回字典的新副本。如果deep为true，则也会递归地复制内部Dictionary和Array键和值。

bool erase(key: Variant) 🔗

如果存在，则按键删除字典条目。如果字典中存在给定的key，则返回true，否则返回false。

注意：在遍历字典时不要擦除条目。您可以改为遍历keys()数组。

Variant find_key(value: Variant) const 🔗

查找并返回关联值等于value的第一个键，如果未找到，则返回null。

注意：null也是一个有效的键。如果在字典中，find_key()可能会给出误导性的结果。

Variant get(key: Variant, default: Variant = null) const 🔗

返回字典中给定key的对应值。如果key不存在，则返回default，如果省略参数，则返回null。

Variant get_or_add(key: Variant, default: Variant = null) 🔗

获取一个值并确保设置了键。如果字典中存在key，则其行为类似于get()。否则，将default值插入字典并返回。

int get_typed_key_builtin() const 🔗

将键入字典键的内置Variant类型作为Variant.Type常量返回。如果未键入键，则返回@GlobalScope.TYPE_NIL。另请参见is_typed_key()。

StringName get_typed_key_class_name() const 🔗

返回类型化字典键的内置类名，如果内置Variant类型是@GlobalScope.TYPE_OBJECT。否则，返回一个空的StringName。另请参见is_typed_key()和Object.get_class()。

Variant get_typed_key_script() const 🔗

返回与此键入字典的键关联的Script实例，如果不存在，则返回null。另请参见is_typed_key()。

int get_typed_value_builtin() const 🔗

将类型化字典值的内置Variant类型作为Variant.Type常量返回。如果未键入值，则返回@GlobalScope.TYPE_NIL。另请参见is_typed_value()。

StringName get_typed_value_class_name() const 🔗

返回类型化字典值的内置类名，如果内置Variant类型是@GlobalScope.TYPE_OBJECT。否则，返回一个空的StringName。另请参见is_typed_value()和Object.get_class()。

Variant get_typed_value_script() const 🔗

返回与此键入字典的值关联的Script实例，如果不存在，则返回null。另请参见is_typed_value()。

bool has(key: Variant) const 🔗

如果字典中包含给定的key条目，则返回true。

var my_dict = {
    "i3D" : 4,
    210 : null,
}

print(my_dict.has("i3D"))   # 输出 true
print(my_dict.has(210))     # 输出 true
print(my_dict.has(4))       # 输出 false

var myDict = new i3D.Collections.Dictionary
{
    { "i3D", 4 },
    { 210, default },
};

S3.Print(myDict.ContainsKey("i3D"));   // 输出 True
S3.Print(myDict.ContainsKey(210));     // 输出 True
S3.Print(myDict.ContainsKey(4));       // 输出 False

在 S3Script 中，这等同于 in 运算符:

if "i3D" in {"i3D": 4}:
    print("The key is here!") # Will be printed.

注意：此方法只要key存在，就返回true，即使其对应的值为null。

bool has_all(keys: Array) const 🔗

如果字典包含给定的 keys 数组中的所有键，则返回 true。

var data = {"width" : 10, "height" : 20}
data.has_all(["height", "width"]) # Returns true

int hash() const 🔗

返回一个哈希的32位整数值，代表字典中的内容。

var dict1 = {"A": 10, "B": 2}
var dict2 = {"A": 10, "B": 2}

print(dict1.hash() == dict2.hash()) # Prints true

var dict1 = new i3D.Collections.Dictionary{{"A", 10}, {"B", 2}};
var dict2 = new i3D.Collections.Dictionary{{"A", 10}, {"B", 2}};

// i3D.Collections.Dictionary has no Hash() method. Use S3.Hash() instead.
S3.Print(S3.Hash(dict1) == S3.Hash(dict2)); // Prints True

注意：条目相同但顺序不同的字典不会有相同的哈希。

注意：哈希值相等的字典不保证相同，因为哈希冲突。相反，哈希值不同的字典保证不同。

bool is_empty() const 🔗

如果字典为空（其大小为0），则返回true。另请参阅size()。

bool is_read_only() const 🔗

如果字典是只读的，则返回true。请参阅make_read_only()。如果使用const关键字声明字典，则字典会自动只读。

bool is_same_typed(dictionary: Dictionary) const 🔗

如果字典的类型与dictionary相同，则返回true。

bool is_same_typed_key(dictionary: Dictionary) const 🔗

如果字典的键与dictionary的键键入相同，则返回true。

bool is_same_typed_value(dictionary: Dictionary) const 🔗

如果字典的值与dictionary的值键入相同，则返回true。

bool is_typed() const 🔗

如果字典是类型化的，则返回true。类型化的字典只能存储其关联类型的键/值，并为[]运算符提供类型安全。类型化字典的方法仍然返回Variant。

bool is_typed_key() const 🔗

如果输入了字典的键，则返回true。

bool is_typed_value() const 🔗

如果输入了字典的值，则返回true。

Array keys() const 🔗

返回字典中的键列表。

void make_read_only() 🔗

使字典为只读，即禁用对字典内容的修改。不适用于嵌套内容，例如嵌套字典的内容。

void merge(dictionary: Dictionary, overwrite: bool = false) 🔗

将dictionary中的条目添加到此字典。默认情况下，除非overwrite为true，否则不会复制重复的键。

var dict = { "item": "sword", "quantity": 2 }
var other_dict = { "quantity": 15, "color": "silver" }

# 默认情况下，已存在键的覆盖功能是禁用的.
dict.merge(other_dict)
print(dict)  # { "item": "sword", "quantity": 2, "color": "silver" }

# 在已开启 “已存在键覆盖功能” 的情况下.
dict.merge(other_dict, true)
print(dict)  # { "item": "sword", "quantity": 15, "color": "silver" }

var dict = new i3D.Collections.Dictionary
{
    ["item"] = "sword",
    ["quantity"] = 2,
};

var otherDict = new i3D.Collections.Dictionary
{
    ["quantity"] = 15,
    ["color"] = "silver",
};

// 默认情况下，已存在键的覆盖功能是禁用的.
dict.Merge(otherDict);
S3.Print(dict); // { "item": "sword", "quantity": 2, "color": "silver" }

// 在已开启 “已存在键覆盖功能” 的情况下.
dict.Merge(otherDict, true);
S3.Print(dict); // { "item": "sword", "quantity": 15, "color": "silver" }

注意： merge() 不是递归的。嵌套的字典被视为键，可以根据overwrite的值来决定是否覆盖，但它们永远不会被合并在一起。

Dictionary merged(dictionary: Dictionary, overwrite: bool = false) const 🔗

返回此字典与其他dictionary合并后的副本。默认情况下，除非overwrite为true，否则不会复制重复的键。另请参阅merge()。此方法可用于快速创建具有默认值的字典：

var base = { "fruit": "apple", "vegetable": "potato" }
var extra = { "fruit": "orange", "dressing": "vinegar" }
# 输出 { "fruit": "orange", "vegetable": "potato", "dressing": "vinegar" }
print(extra.merged(base))
# 输出 { "fruit": "apple", "vegetable": "potato", "dressing": "vinegar" }
print(extra.merged(base, true))

bool recursive_equal(dictionary: Dictionary, recursion_count: int) const 🔗

如果两个字典包含相同的键和值，则返回true，递归比较内部Dictionary和Array键和值。

bool set(key: Variant, value: Variant) 🔗

将给定key处的元素值设置为给定value。这与使用[]运算符（数组[index]=value）相同。

int size() const 🔗

返回字典中的条目数。空字典（{}）总是返回0。另请参见is_empty()。

void sort() 🔗

按键就地对字典进行排序。这可用于确保具有相同内容的字典在获取keys()、获取values()和转换为字符串时产生等效的结果。当希望JSON表示与内存中的表示一致时，这也很有用，并且对于存储在需要对字典进行排序的数据库中很有用。

Array values() const 🔗

返回此字典中的值列表。

运算符说明¶

bool operator !=(right: Dictionary) 🔗

如果两个字典不包含相同的键和值，则返回true。

bool operator ==(right: Dictionary) 🔗

如果两个字典包含相同的键和值，则返回true。条目的顺序无关紧要。

注意：在C#中，按照惯例，此运算符通过引用进行比较。如果您需要按值进行比较，请遍历两个字典。

Variant operator [](key: Variant) 🔗

返回字典中给定key的对应值。如果条目不存在，则失败并返回null。为了安全访问，请使用get()或has()。