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...

Dictionary

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

描述

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

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

字典的创建：

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

你可以通过键来访问字典中对应的值。上面的例子中，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]

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

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

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

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

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

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

# 这是有效的字典。
# 要访问下面的 "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"},
}

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

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

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

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

备注

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

教程

构造函数

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 = {
    "Godot" : 4,
    210 : null,
}

print(my_dict.has("Godot")) # 输出 true
print(my_dict.has(210))     # 输出 true
print(my_dict.has(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 位整数哈希值。

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

print(dict1.hash() == dict2.hash()) # 输出 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" }

注意：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。与使用 [] 运算符相同（array[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()。