### **Godot `Dictionary` 类用法详解**

#### **基础用法**

------

**1. 创建字典**

```gdscript
# 空字典
var empty_dict = {}

# 初始化字典
var simple_dict = {"name": "Godot", "version": 4.0}

# 使用变量作为键和值
var key_name = "language"
var key_value = "GDScript"
var variable_dict = {key_name: key_value}

# 混合键和值类型
var mixed_dict = {
    "integer_key": 1,
    "string_key": "value",
    3: [1, 2, 3], # 数组作为值
    "nested_dict": {"nested_key": "nested_value"}
}
```


------

**2. 访问字典值**

```gdscript
var my_dict = {"name": "Godot", "version": 4.0}

# 通过键访问值
print(my_dict["name"]) # 输出: Godot

# 通过点语法访问（仅限字符串键）
print(my_dict.version) # 输出: 4.0

# 使用 `get()` 方法访问
print(my_dict.get("nonexistent_key", "default_value")) # 输出: default_value
```

------

**3. 修改或添加键值对**

```gdscript
var my_dict = {"name": "Godot"}

# 修改已有键的值
my_dict["name"] = "Godot Engine"

# 添加新的键值对
my_dict["year"] = 2024

print(my_dict) # 输出: {"name": "Godot Engine", "year": 2024}
```

------

**4. 删除键值对**

```gdscript
var my_dict = {"name": "Godot", "version": 4.0}

# 使用 erase() 删除
my_dict.erase("version")

print(my_dict) # 输出: {"name": "Godot"}
```

------

**5. 检查键是否存在**

```gdscript
var my_dict = {"name": "Godot"}

# 使用 has() 方法
if my_dict.has("name"):
    print("Key exists!") # 输出: Key exists!

# 等价的 `in` 语法
if "name" in my_dict:
    print("Key exists!") # 输出: Key exists!
```

------

**6. 遍历字典**

```gdscript
var groceries = {"Apple": 10, "Banana": 5, "Cherry": 12}

# 遍历键
for fruit in groceries:
    print(fruit, groceries[fruit])

# 遍历键和值
for key, value in groceries:
    print("Key:", key, "Value:", value)
```

------

#### **方法说明**

**1. `clear()`** 清空字典的所有条目。

```gdscript
var my_dict = {"name": "Godot", "version": 4.0}
my_dict.clear()
print(my_dict) # 输出: {}
```

------

**2. `duplicate(deep: bool = false)`** 创建字典的副本。若 `deep` 为 `true`，内部的嵌套字典或数组也会递归复制。

```gdscript
var original = {"key": [1, 2, 3]}
var shallow_copy = original.duplicate()
shallow_copy["key"].append(4)

print(original)       # 输出: {"key": [1, 2, 3, 4]}
print(shallow_copy)   # 输出: {"key": [1, 2, 3, 4]}

var deep_copy = original.duplicate(true)
deep_copy["key"].append(5)

print(original)       # 输出: {"key": [1, 2, 3, 4]}
print(deep_copy)      # 输出: {"key": [1, 2, 3, 4, 5]}
```

------

**3. `erase(key: Variant)`** 移除与指定键关联的条目。

```gdscript
var my_dict = {"name": "Godot"}
my_dict.erase("name")
print(my_dict) # 输出: {}
```

------

**4. `find_key(value: Variant)`** 查找给定值对应的第一个键，未找到则返回 `null`。

```gdscript
var my_dict = {"key1": "value1", "key2": "value2"}
print(my_dict.find_key("value1")) # 输出: key1
print(my_dict.find_key("nonexistent")) # 输出: null
```

------

**5. `get(key: Variant, default: Variant = null)`** 安全地获取键对应的值，若键不存在则返回默认值。

```gdscript
var my_dict = {"name": "Godot"}
print(my_dict.get("name", "default")) # 输出: Godot
print(my_dict.get("nonexistent_key", "default")) # 输出: default
```

------

**6. `has_all(keys: Array)`** 检查字典是否包含指定数组中的所有键。

```gdscript
var my_dict = {"width": 10, "height": 20}
print(my_dict.has_all(["width", "height"])) # 输出: true
print(my_dict.has_all(["width", "depth"]))  # 输出: false
```

------

**7. `keys()`** 返回字典中所有键的数组。

```gdscript
var my_dict = {"name": "Godot", "version": 4.0}
print(my_dict.keys()) # 输出: ["name", "version"]
```

------

**8. `values()`** 返回字典中所有值的数组。

```gdscript
var my_dict = {"name": "Godot", "version": 4.0}
print(my_dict.values()) # 输出: ["Godot", 4.0]
```

------

**9. `merge(dictionary: Dictionary, overwrite: bool = false)`** 合并另一个字典的键值对。默认不覆盖已有键，若 `overwrite` 为 `true` 则覆盖。

```gdscript
var dict1 = {"key1": "value1", "key2": "value2"}
var dict2 = {"key2": "new_value2", "key3": "value3"}

dict1.merge(dict2)
print(dict1) # 输出: {"key1": "value1", "key2": "value2", "key3": "value3"}

dict1.merge(dict2, true)
print(dict1) # 输出: {"key1": "value1", "key2": "new_value2", "key3": "value3"}
```

------

**10. `size()`** 返回字典中条目的数量。

```gdscript
var my_dict = {"name": "Godot", "version": 4.0}
print(my_dict.size()) # 输出: 2
```

------

# **运算符**

------

**1. `==` 和 `!=`** 比较两个字典的内容是否相同。

```gdscript
var dict1 = {"key1": "value1", "key2": "value2"}
var dict2 = {"key1": "value1", "key2": "value2"}
print(dict1 == dict2) # 输出: true

var dict3 = {"key2": "value2", "key1": "value1"}
print(dict1 == dict3) # 输出: true (顺序无关)
```

**2. `[]` 访问操作符**

```gdscript
var my_dict = {"name": "Godot"}
print(my_dict["name"]) # 输出: Godot
```

------
