Dictionary¶

字典类型。

描述¶

字典类型。关联容器，包含由唯一键引用的值。字典由键（必须是唯一的）和值对组成。当添加元素时，字典将保留插入顺序，即使在打印字典时可能不会反映出来。在其他编程语言中，这种数据结构有时被称为哈希表或关联数组。

您可以通过在大括号 {} 中放置一个以逗号分隔的 key: value 对的列表来定义一个字典。

不支持在迭代元素时擦除元素，会导致未定义行为。

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

创建字典：

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_dir["White"] 会返回 50。你也可以写成 points_dir.White，效果都是相同的。但是如果你需要访问的键不是一个固定的字符串（比如数字或变量）时，你需要使用方括号。

export(String, "White", "Yellow", "Orange") var my_color
var points_dir = {"White": 50, "Yellow": 75, "Orange": 100}
func _ready():
    # 这里我们不能使用点，因为‘my_color’是个变量。
    var points = points_dir[my_color]

在上方的代码中，points 会被赋值为 my_color中选取的颜色。

字典可以容纳更加复杂的数据：

my_dir = {"First Array": [1, 2, 3, 4]} # 将一个数组分配给一个字符串键。

如果想要给字典添加一个键，可以像访问已有的键一样：

var points_dir = {"White": 50, "Yellow": 75, "Orange": 100}
points_dir["Blue"] = 150 # 添加键"Blue"，并将其数值设定为150

最终，同一个字典内可以容纳不同类型的键和值：

# 这是一个合法的字典。
# 使用`my_dir.sub_dir.sub_key`或`my_dir["sub_dir"]["sub_key"]`来访问下方的字符串"Nested value"。
# 根据你不同的需求可以修改索引样式。
var my_dir = {
    "String Key": 5,
    4: [1, 2, 3],
    7: "Hello",
    "sub_dir": {"sub_key": "Nested value"},
}

注意：和数组不同的是，你不能直接进行字典对比：

array1 = [1, 2, 3]
array2 = [1, 2, 3]

func compare_arrays():
    print(array1 == array2) # 会输出true。

dir1 = {"a": 1, "b": 2, "c": 3}
dir2 = {"a": 1, "b": 2, "c": 3}

func compare_dictionaries():
    print(dir1 == dir2) # 不会输出true。

想要对比字典，首先需要用 hash 计算字典哈希。

dir1 = {"a": 1, "b": 2, "c": 3}
dir2 = {"a": 1, "b": 2, "c": 3}

func compare_dictionaries():
    print(dir1.hash() == dir2.hash()) # 会输出true。

注意：当使用 const 来声明字典时，字典本身依然可以通过定义键的数值来进行修改。使用 const 只能防止在它初始化完成后被给予另一个数值。

教程¶

方法¶

void	clear ( )
Dictionary	duplicate ( bool deep=false )
bool	empty ( )
bool	erase ( Variant key )
Variant	get ( Variant key, Variant default=null )
bool	has ( Variant key )
bool	has_all ( Array keys )
int	hash ( )
Array	keys ( )
int	size ( )
Array	values ( )

方法说明¶

void clear ( )

清除字典，删除所有键/值对。

Dictionary duplicate ( bool deep=false )

创建一个字典的副本，并返回它。deep 参数使内部字典和数组被递归复制，但不适用于对象。

bool empty ( )

如果字典为空，返回true。

bool erase ( Variant key )

依据key擦除字典的键值对。如果指定的 key 存在于字典中，返回 true ，否则返回 false 。

注意: 在迭代字典时不要擦除元素。可以迭代 keys 数组。

Variant get ( Variant key, Variant default=null )

返回Dictionary中指定键的当前值。如果键不存在，则该方法返回可选默认参数的值；如果省略，则返回null。

bool has ( Variant key )

如果字典有一个给定的键，返回true。

注：这相当于使用in运算符，如下所示。

# Will evaluate to `true`.
if "godot" in {"godot": "engine"}:
    pass

只要键存在，即使相关的值是null，这个方法（就像in运算符一样）也会评估为true。

bool has_all ( Array keys )

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

int hash ( )

返回一个代表字典内容的哈希整数值。这可以用来比较字典的值。

var dict1 = {0: 10}
var dict2 = {0: 10}
# The line below prints `true`, whereas it would have printed `false` if both variables were compared directly.
print(dict1.hash() == dict2.hash())

注意：具有相同键/值但顺序不同的字典将有不同的哈希值。

Array keys ( )

返回Dictionary中的键列表。

int size ( )

返回字典中键的数量。

Array values ( )

返回Dictionary中的值列表。