NodePath
Предварительно проанализированный путь дерева сцены.
Описание
Встроенный тип Variant NodePath представляет собой путь к узлу или свойству в иерархии узлов. Он разработан для эффективной передачи во многие встроенные методы (такие как Node.get_node(), Object.set_indexed(), Tween.tween_property() и т. д.) без жесткой зависимости от узла или свойства, на которые они указывают.
Путь к узлу представлен как String, состоящий из разделенных косой чертой (/) имен узлов и разделенных двоеточием (:) имен свойств (также называемых «подименами»). Подобно пути файловой системы, ".." и "." являются специальными именами узлов. Они ссылаются на родительский узел и текущий узел соответственно.
Следующие примеры являются путями относительно текущего узла:
^"A" # Указывает на прямого потомка А.
^"A/B" # Указывает на дочерний элемент А — B.
^"." # Указывает на текущий узел.
^".." # Указывает на родительский узел.
^"../C" # Указывает на родственный узел C.
^"../.." # Указывает на прародительский узел.
Начальная косая черта означает, что путь абсолютный и начинается с SceneTree:
^"/root" # Указывает на корневое окно SceneTree.
^"/root/Title" # Может указывать на корневой узел основной сцены с именем «Title».
^"/root/Global" # Может указывать на автоматически загруженный узел или сцену с именем «Global».
Несмотря на свое название, пути узлов также могут указывать на свойство:
^":position" # Указывает на положение этого объекта.
^":position:x" # Указывает на положение данного объекта по оси x.
^"Camera3D:rotation:y" # Указывает на дочернюю камеру Camera3D и ее вращение по оси Y.
^"/root:size:x" # Указывает на корневое окно и его ширину.
В некоторых ситуациях можно опустить ведущий : при указании на свойство объекта. Например, это касается Object.set_indexed() и Tween.tween_property(), поскольку эти методы вызывают get_as_property_path() под капотом. Однако обычно рекомендуется сохранять префикс :.
Пути узлов не могут проверять, являются ли они допустимыми, и могут указывать на узлы или свойства, которые не существуют. Их значение полностью зависит от контекста, в котором они используются.
Обычно вам не нужно беспокоиться о типе NodePath, поскольку строки автоматически преобразуются в этот тип при необходимости. Бывают случаи, когда определение путей узлов полезно. Например, экспортированные свойства NodePath позволяют вам легко выбирать любой узел в текущей редактируемой сцене. Они также автоматически обновляются при перемещении, переименовании или удалении узлов в редакторе дерева сцены. См. также @GDScript.@export_node_path.
См. также StringName, который является похожим типом, разработанным для оптимизированных строк.
Примечание: В булевом контексте NodePath будет оцениваться как false, если он пуст (NodePath("")). В противном случае NodePath всегда будет оцениваться как true.
Примечание
Существуют заметные различия при использовании данного API с C#. Подробнее см. API различия C# и GDScript.
Обучающие материалы
Конструкторы
NodePath() |
|
Методы
get_as_property_path() const |
|
get_concatenated_names() const |
|
get_concatenated_subnames() const |
|
get_name_count() const |
|
get_subname(idx: int) const |
|
get_subname_count() const |
|
hash() const |
|
is_absolute() const |
|
is_empty() const |
|
Операторы
operator !=(right: NodePath) |
|
operator ==(right: NodePath) |
Описания конструктора
Создает пустой NodePath.
NodePath NodePath(from: NodePath)
Создает NodePath как копию заданного NodePath.
NodePath NodePath(from: String)
Создает NodePath из String. Созданный путь является абсолютным, если предваряется косой чертой (см. is_absolute()).
"Подимена", необязательно включаемые после пути к целевому узлу, могут указывать на свойства, а также могут быть вложенными.
Следующие строки могут быть допустимыми путями узлов:
# Указывает на узел Sprite2D.
"Level/RigidBody2D/Sprite2D"
# Указывает на узел Sprite2D и его ресурс «texture».
# get_node() извлечет Sprite2D, в то время как get_node_and_resource()
# извлечет как узел Sprite2D, так и ресурс «texture».
"Level/RigidBody2D/Sprite2D:texture"
# Указывает на узел Sprite2D и его свойство «position».
"Level/RigidBody2D/Sprite2D:position"
# Указывает на узел Sprite2D и компонент «x» его свойства «position».
"Level/RigidBody2D/Sprite2D:position:x"
# Указывает на узел RigidBody2D как на абсолютный путь, начинающийся от SceneTree.
"/root/Level/RigidBody2D"
Примечание: В GDScript также можно преобразовать постоянную строку в путь к узлу, добавив к ней префикс ^. ^"path/to/node" эквивалентно NodePath("path/to/node").
Описания метода
NodePath get_as_property_path() const 🔗
Возвращает копию этого пути узла с префиксом двоеточия (:), преобразуя его в чистый путь свойства без имен узлов (относительно текущего узла).
# node_path указывает на свойство «x» дочернего узла с именем «position».
var node_path = ^"position:x"
# property_path указывает на «position» по оси «x» этого узла.
var property_path = node_path.get_as_property_path()
print(property_path) # Выводит ":position:x"
// node_path указывает на свойство «x» дочернего узла с именем «position».
var nodePath = new NodePath("position:x");
// property_path указывает на «position» по оси «x» этого узла.
NodePath propertyPath = nodePath.GetAsPropertyPath();
GD.Print(propertyPath); // Выводит ":position:x"
StringName get_concatenated_names() const 🔗
Возвращает все имена узлов, объединенные с помощью символа косой черты (/) как единое StringName.
StringName get_concatenated_subnames() const 🔗
Возвращает все подимена свойств, объединенные символом двоеточия (:) как единое StringName.
var node_path = ^"Sprite2D:texture:resource_name"
print(node_path.get_concatenated_subnames()) # Выводит "texture:resource_name"
var nodePath = new NodePath("Sprite2D:texture:resource_name");
GD.Print(nodePath.GetConcatenatedSubnames()); // Выводит "texture:resource_name"
StringName get_name(idx: int) const 🔗
Возвращает имя узла, указанное idx, начиная с 0. Если idx выходит за пределы, генерируется ошибка. См. также get_subname_count() и get_name_count().
var sprite_path = NodePath("../RigidBody2D/Sprite2D")
print(sprite_path.get_name(0)) # Выводит ".."
print(sprite_path.get_name(1)) # Выводит "RigidBody2D"
print(sprite_path.get_name(2)) # Выводит "Sprite"
var spritePath = new NodePath("../RigidBody2D/Sprite2D");
GD.Print(spritePath.GetName(0)); // Выводит ".."
GD.Print(spritePath.GetName(1)); // Выводит "PathFollow2D"
GD.Print(spritePath.GetName(2)); // Выводит "Sprite"
Возвращает количество имен узлов в пути. Подимена свойств не включены.
Например, "../RigidBody2D/Sprite2D:texture" содержит 3 имени узлов.
StringName get_subname(idx: int) const 🔗
Возвращает имя свойства, указанное idx, начиная с 0. Если idx выходит за пределы, генерируется ошибка. См. также get_subname_count().
var path_to_name = NodePath("Sprite2D:texture:resource_name")
print(path_to_name.get_subname(0)) # Выводит "texture"
print(path_to_name.get_subname(1)) # Выводит "resource_name"
var pathToName = new NodePath("Sprite2D:texture:resource_name");
GD.Print(pathToName.GetSubname(0)); // Выводит "texture"
GD.Print(pathToName.GetSubname(1)); // Выводит "resource_name"
int get_subname_count() const 🔗
Возвращает количество имен свойств («подимен») в пути. Каждое подимя в пути узла указывается после символа двоеточия (:).
Например, "Level/RigidBody2D/Sprite2D:texture:resource_name" содержит 2 подимени.
Возвращает 32-битное хэш-значение, представляющее содержимое пути узла.
Примечание: Пути узлов с одинаковыми значениями хэша не гарантированно будут одинаковыми из-за коллизий хэшей. Пути узлов с разными значениями хэшей гарантированно будут разными.
Возвращает true, если путь к узлу абсолютный. В отличие от относительного пути, абсолютный путь представлен начальным символом косой черты (/) и всегда начинается с SceneTree. Его можно использовать для надежного доступа к узлам из корневого узла (например, "/root/Global", если существует автозагрузка с именем "Global").
Возвращает true, если путь к узлу был создан из пустой String ("").
NodePath slice(begin: int, end: int = 2147483647) const 🔗
Возвращает срез NodePath от begin (включительно) до end (исключительно) как новый NodePath.
Абсолютное значение begin и end будет ограничено суммой get_name_count() и get_subname_count(), поэтому значение по умолчанию для end делает его срезом до конца NodePath по умолчанию (т. е. path.slice(1) является сокращением для path.slice(1, path.get_name_count() + path.get_subname_count())).
Если begin или end отрицательны, они будут относительными к концу NodePath (т. е. path.slice(0, -2) является сокращением для path.slice(0, path.get_name_count() + path.get_subname_count() - 2)).
Описания оператора
bool operator !=(right: NodePath) 🔗
Возвращает true, если пути двух узлов не равны.
bool operator ==(right: NodePath) 🔗
Возвращает true, если два пути узлов равны, то есть они состоят из одинаковых имен узлов и подимен в одинаковом порядке.