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

Встроенная структура данных, содержащая пары ключ-значение.

Описание

Dictionaries (Словари) — это ассоциативные контейнеры, содержащие значения, на которые ссылаются уникальные ключи. Словари сохраняют порядок добавления новых записей. В других языках программирования эта структура данных часто называется "hash map" или ассоциативным массивом.

Вы можете определить словарь, поместив список пар ключ: значение, разделенных запятыми, в фигурные скобки {}.

Создание словаря:

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, что эквивалентно. Однако вам придется использовать синтаксис скобок, если ключ, с помощью которого вы обращаетесь к словарю, не является фиксированной строкой (например, числом или переменной).

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

Словари могут содержать более сложные данные:

var my_dict = {
    "First Array": [1, 2, 3, 4] # Назначает Массив Строковому ключу (String key).
}

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

Чтобы добавить ключ в существующий словарь, получите к нему доступ как к существующему ключу и назначьте ему:

var points_dict = { "White": 50, "Yellow": 75, "Orange": 100 }
points_dict["Blue"] = 150 # Add "Blue" as a key and assign 150 as its value.

var pointsDict = new Godot.Collections.Dictionary
{
    { "White", 50 },
    { "Yellow", 75 },
    { "Orange", 100 },
};
pointsDict["Blue"] = 150; // Add "Blue" as a key and assign 150 as its value.

Наконец, нетипизированные словари могут содержать различные типы ключей и значений в одном и том же словаре:

# Это действительный словарь.
# Чтобы получить доступ к строке "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:

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` - значение.
}

Чтобы обеспечить определённый тип ключей и значений, можно создать typed dictionary. Типизированные словари могут содержать только ключи и значения заданных типов или наследуемые от заданных классов:

# Создает типизированный словарь со строковыми ключами и целочисленными значениями.
# Попытка использовать любой другой тип для ключей или значений приведет к ошибке.
var typed_dict: Dictionary[String, int] = {
    "some_key": 1,
    "some_other_key": 2,
}

# Создает типизированный словарь со строковыми ключами и значениями любого типа.
# Попытка использовать любой другой тип ключей приведет к ошибке.
var typed_dict_key_only: Dictionary[String, Variant] = {
    "some_key": 12.34,
    "some_other_key": "string",
}

// Создает типизированный словарь со строковыми ключами и целочисленными значениями.
// Попытка использовать любой другой тип для ключей или значений приведет к ошибке.
var typedDict = new Godot.Collections.Dictionary<String, int> {
    {"some_key", 1},
    {"some_other_key", 2},
};

// Создает типизированный словарь со строковыми ключами и значениями любого типа.
// Попытка использовать любой другой тип ключей приведет к ошибке.
var typedDictKeyOnly = new Godot.Collections.Dictionary<String, Variant> {
    {"some_key", 12.34},
    {"some_other_key", "string"},
};

Примечание: Словари всегда передаются по ссылке. Чтобы получить копию словаря, которую можно изменять независимо от исходного, используйте duplicate().

Примечание: Удаление элементов при итерации по словарям не поддерживается и приведет к непредсказуемому поведению.

Примечание: В логическом контексте словарь будет оцениваться как false, если он пуст ({}). В противном случае словарь всегда будет оцениваться как true.

Примечание

Существуют заметные различия при использовании данного API с C#. Подробнее см. API различия C# и 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
Dictionary	duplicate_deep(deep_subresources_mode: int = 1) 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 🔗

Возвращает новую копию словаря.

По умолчанию возвращается поверхностная копия: все вложенные ключи и значения Array, Dictionary и Resource используются совместно с исходным словарем. Изменение любого из них в одном словаре также повлияет на них в другом.

Если deep равен true, возвращается глубокая копия: все вложенные массивы и словари также дублируются (рекурсивно). Однако любой Resource по-прежнему используется совместно с исходным словарем.

Dictionary duplicate_deep(deep_subresources_mode: int = 1) const 🔗

Дублирует этот словарь, глубоко, как duplicate() при передаче true, с дополнительным контролем над обработкой подресурсов.

deep_subresources_mode должен быть одним из значений из DeepDuplicateMode. По умолчанию дублируются только внутренние ресурсы (рекурсивно).

bool erase(key: Variant) 🔗

Удаляет запись словаря по ключу, если она существует. Возвращает true, если заданный key существовал в словаре, в противном случае 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, если параметр опущен.

Примечание: Если аргумент default является вычислительно затратным или имеет нежелательные побочные эффекты, рассмотрите возможность использования метода has() вместо него:

# Всегда вызывает `expensive_function()`.
dict.get("key", expensive_function())
# Вызывает `expensive_function()` только если ключ не существует.
dict.get("key") if dict.has("key") else expensive_function()

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 🔗

Возвращает true, если словарь содержит запись с заданным key.

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("Ключ здесь!") # Будет напечатано.

Примечание: Этот метод возвращает true до тех пор, пока существует key, даже если его соответствующее значение равно null.

bool has_all(keys: Array) const 🔗

Возвращает true, если словарь содержит все ключи в заданном массиве keys.

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

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 🔗

Возвращает true, если словарь пуст (его размер 0). См. также size().

bool is_read_only() const 🔗

Возвращает true, если словарь доступен только для чтения. См. make_read_only(). Словари автоматически доступны только для чтения, если объявлены с ключевым словом const.

bool is_same_typed(dictionary: Dictionary) const 🔗

Возвращает true, если словарь имеет тот же тип, что и dictionary.

bool is_same_typed_key(dictionary: Dictionary) const 🔗

Возвращает true, если ключи словаря введены так же, как ключи dictionary.

bool is_same_typed_value(dictionary: Dictionary) const 🔗

Возвращает true, если значения словаря типизированы так же, как значения dictionary.

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

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

Возвращает true, если два словаря содержат одинаковые ключи и значения, внутренние ключи и значения Dictionary и Array сравниваются рекурсивно.

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

Устанавливает значение элемента по заданному ключу key равным заданному значению value. Возвращает true, если значение установлено успешно. В случае ошибки возвращает false, если словарь доступен только для чтения или если key и value не соответствуют типам словаря. Это аналогично использованию оператора [] (dict[key] = value).

int size() const 🔗

Возвращает количество записей в словаре. Пустые словари ({ }) всегда возвращают 0. См. также is_empty().

void sort() 🔗

Сортирует словарь в порядке возрастания по ключу. Окончательный порядок зависит от сравнения «меньше чем» (<) между ключами.

var numbers = { "c": 2, "a": 0, "b": 1 }
numbers.sort()
print(numbers) # Выводит { "a": 0, "b": 1, "c": 2 }

Этот метод гарантирует, что записи словаря будут упорядочены последовательно, когда вызываются keys() или values(), или когда словарь необходимо преобразовать в строку с помощью @GlobalScope.str() или JSON.stringify().

Array values() const 🔗

Возвращает список значений в этом словаре.

Описания оператора

bool operator !=(right: Dictionary) 🔗

Возвращает true, если два словаря не содержат одинаковые ключи и значения.

bool operator ==(right: Dictionary) 🔗

Возвращает true, если два словаря содержат одинаковые ключи и значения. Порядок записей не имеет значения.

Примечание: В C# по соглашению этот оператор сравнивает по ссылке. Если вам нужно сравнить по значению, выполните итерацию по обоим словарям.

Variant operator [](key: Variant) 🔗

Возвращает соответствующее значение для указанного key в словаре. Если запись не существует, происходит сбой и возвращается null. Для безопасного доступа используйте get() или has().