Dictionary

包含键值对的内置数据结构。

描述

字典是关系容器，包含的值（Value）由唯一的键（Key）引用。添加新条目时，字典会保持插入顺序。在其他编程语言中，这种数据结构有时也称为哈希表或关联数组。

在大括号 {} 中放置用逗号分隔的一对对 键: 值 列表就可以定义字典。

字典的创建：

GDScriptC#

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 Godot.Collections.Dictionary(); // 创建空字典。
var pointsDict = new Godot.Collections.Dictionary
{
    {"White", 50},
    {"Yellow", 75},
    {"Orange", 100}
};

你可以通过键来访问字典中对应的值。上面的例子中，points_dict["White"] 会返回 50。你也可以写 points_dict.White，和前面的写法是等价的。不过如果用来访问字典的键不是固定字符串的话（例如数字或者变量），那么就只能使用方括号语法。

GDScriptC#

@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 Godot.Collections.Dictionary _pointsDict = new Godot.Collections.Dictionary
{
    {"White", 50},
    {"Yellow", 75},
    {"Orange", 100}
};
public override void _Ready()
{
    int points = (int)_pointsDict[MyColor];
}

在上面的代码中，points 会被赋值为与 my_color 中选中的颜色相对应的值。

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

GDScriptC#

var my_dict = {
    "First Array": [1, 2, 3, 4] # 将 Array 赋给 String 键。
}

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

要往已有字典中添加键，请像已有键一样进行访问并赋值：

GDScriptC#

var points_dict = {"White": 50, "Yellow": 75, "Orange": 100}
points_dict["Blue"] = 150 # 将 "Blue" 添加为键，并将 150 赋为它的值。

var pointsDict = new Godot.Collections.Dictionary
{
    {"White", 50},
    {"Yellow", 75},
    {"Orange", 100}
};
pointsDict["Blue"] = 150; // 将 "Blue" 添加为键，并将 150 赋为它的值。

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

GDScriptC#

# 这是有效的字典。
# 要访问下面的 "Nested value"，请使用 `my_dict.sub_dict.sub_key` 或 `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"，请使用 `((Godot.Collections.Dictionary)myDict["sub_dict"])["sub_key"]`。
var myDict = new Godot.Collections.Dictionary {
    {"String Key", 5},
    {4, new Godot.Collections.Array{1,2,3}},
    {7, "Hello"},
    {"sub_dict", new Godot.Collections.Dictionary{{"sub_key", "Nested value"}}}
};

字典中的键可以用 for 关键字进行遍历：

GDScriptC#

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

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

注意：字典始终按引用传递。要获取字典的副本，能独立于原字典进行修改，请使用 duplicate。

注意：**不支持**在遍历字典时清除元素，可能造成无法预知的行为。

备注

通过 C# 使用该 API 时会有显著不同，详见 C# API 与 GDScript 的差异。

教程

• GDScript 基础：字典

• 3D 体素演示

• 操作系统测试演示

构造函数

方法

运算符

构造函数说明

Dictionary Dictionary() 🔗

构造空的 Dictionary。

Dictionary Dictionary(from: Dictionary)

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

方法说明

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 值将被插入到字典中并返回。

bool has(key: Variant) const 🔗

如果该字典包含给定的键 key，则返回 true。

GDScriptC#

var my_dict = {
    "Godot" : 4,
    210 : null,
}
print(my_dict.has("Godot")) # 输出 true
print(my_dict.has(210))     # 输出 true
print(my_dict.has(4))       # 输出 false

var myDict = new Godot.Collections.Dictionary
{
    { "Godot", 4 },
    { 210, default },
};
GD.Print(myDict.ContainsKey("Godot")); // 输出 true
GD.Print(myDict.ContainsKey(210));     // 输出 true
GD.Print(myDict.ContainsKey(4));       // 输出 false

在 GDScript 中等价于 in 运算符：

if "Godot" in {"Godot": 4}:
    print("这个键存在！") # 会进行输出。

注意：只要键 key 存在，该方法就会返回 true，即便这个键对应的值为 null。

bool has_all(keys: Array) const 🔗

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

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

int hash() const 🔗

返回代表该字典内容的 32 位整数哈希值。

GDScriptC#

var dict1 = {"A": 10, "B": 2}
var dict2 = {"A": 10, "B": 2}
print(dict1.hash() == dict2.hash()) # 输出 true

var dict1 = new Godot.Collections.Dictionary{{"A", 10}, {"B", 2}};
var dict2 = new Godot.Collections.Dictionary{{"A", 10}, {"B", 2}};
// Godot.Collections.Dictionary 没有 Hash() 方法。请改用 GD.Hash()。
GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // 输出 true

注意：如果两个字典条目相同，但顺序不同，则哈希值也不同。

注意：哈希值相同的字典不保证相同，因为可能存在哈希碰撞。相对地，哈希值不同的字典保证不同。

bool is_empty() const 🔗

如果该字典为空（大小为 0），则返回 true。另见 size。

bool is_read_only() const 🔗

如果该字典是只读的，则返回 true 。见 make_read_only。用 const 关键字声明的字典自动只读。

Array keys() const 🔗

返回该字典中的键列表。

void make_read_only() 🔗

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

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

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

GDScriptC#

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 Godot.Collections.Dictionary
{
    ["item"] = "sword",
    ["quantity"] = 2,
};
var otherDict = new Godot.Collections.Dictionary
{
    ["quantity"] = 15,
    ["color"] = "silver",
};
// 默认情况下禁用覆盖已有键。
dict.Merge(otherDict);
GD.Print(dict); // { "item": "sword", "quantity": 2, "color": "silver" }
// 启用覆盖已有键。
dict.Merge(otherDict, true);
GD.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))

另见 merge。

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

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

int size() const 🔗

返回该字典中条目的数量。空字典（{ }）始终返回 0。另见 is_empty。

Array values() const 🔗

返回该字典中的值列表。

运算符说明

bool operator !=(right: Dictionary) 🔗

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

bool operator ==(right: Dictionary) 🔗

如果两个字典包含的键、值心相同，则返回 true 。条目顺序并不重要。

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

Variant operator [](key: Variant) 🔗

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