NodePath

预先解析的场景树路径。

描述

The NodePath built-in Variant type represents a path to a node or property in a hierarchy of nodes. It is designed to be efficiently passed into many built-in methods (such as Node.get_node, Object.set_indexed, Tween.tween_property, etc.) without a hard dependence on the node or property they point to.

A node path is represented as a String composed of slash-separated (/) node names and colon-separated (:) property names (also called “subnames”). Similar to a filesystem path, ".." and "." are special node names. They refer to the parent node and the current node, respectively.

The following examples are paths relative to the current node:

^"A"     # Points to the direct child A.
^"A/B"   # Points to A's child B.
^"."     # Points to the current node.
^".."    # Points to the parent node.
^"../C"  # Points to the sibling node C.
^"../.." # Points to the grandparent node.

A leading slash means the path is absolute, and begins from the SceneTree:

^"/root"            # Points to the SceneTree's root Window.
^"/root/Title"      # May point to the main scene's root node named "Title".
^"/root/Global"     # May point to an autoloaded node or scene named "Global".

Despite their name, node paths may also point to a property:

^":position"           # Points to this object's position.
^":position:x"         # Points to this object's position in the x axis.
^"Camera3D:rotation:y" # Points to the child Camera3D and its y rotation.
^"/root:size:x"        # Points to the root Window and its width.

In some situations, it’s possible to omit the leading : when pointing to an object’s property. As an example, this is the case with Object.set_indexed and Tween.tween_property, as those methods call get_as_property_path under the hood. However, it’s generally recommended to keep the : prefix.

Node paths cannot check whether they are valid and may point to nodes or properties that do not exist. Their meaning depends entirely on the context in which they’re used.

You usually do not have to worry about the NodePath type, as strings are automatically converted to the type when necessary. There are still times when defining node paths is useful. For example, exported NodePath properties allow you to easily select any node within the currently edited scene. They are also automatically updated when moving, renaming or deleting nodes in the scene tree editor. See also @GDScript.@export_node_path.

See also StringName, which is a similar type designed for optimized strings.

Note: In a boolean context, a NodePath will evaluate to false if it is empty (NodePath("")). Otherwise, a NodePath will always evaluate to true.

备注

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

教程

• 2D 角色扮演游戏（RPG）演示

构造函数

方法

运算符

构造函数说明

NodePath NodePath() 🔗

构造空的 NodePath。

NodePath NodePath(from: NodePath)

构造一个 NodePath 作为给定 NodePath 的副本。

NodePath NodePath(from: String)

从 String 构造 NodePath。如果以斜杠为前缀，则创建的路径是绝对路径（请参阅 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 节点及其“位置（position）”属性的 “x” 分量。
"Level/RigidBody2D/Sprite2D:position:x"
# 指向 RigidBody2D 节点作为从 SceneTree 开始的绝对路径。
"/root/Level/RigidBody2D"

注意：在 GDScript 中，也可以通过在常量字符串前面加上 ^ 前缀，来将常量字符串转换为节点路径。^"path/to/node" 相当于 NodePath("path/to/node")。

方法说明

NodePath get_as_property_path() const 🔗

返回该节点路径带有冒号字符（:）前缀的副本，将其转换为没有节点名称的纯属性路径（相对于当前节点）。

GDScriptC#

# node_path 指向名为 “position” 的子节点的 “x” 属性。
var node_path = ^"position:x"
# property_path 指向该节点在 “x” 轴上的 “position”。
var property_path = node_path.get_as_property_path()
print(property_path) # 打印 “:position:x”

// node_path 指向名为 “position” 的子节点的 “x” 属性。
var nodePath = new NodePath("position:x");
// property_path 指向该节点在 “x” 轴上的 “position”。
NodePath propertyPath = nodePath.GetAsPropertyPath();
GD.Print(propertyPath); // 打印 “:position:x”。

StringName get_concatenated_names() const 🔗

将与斜杠字符（/）连接的所有节点名称作为单个 StringName 返回。

StringName get_concatenated_subnames() const 🔗

将与冒号字符（:）连接的所有属性子名称作为单个 StringName 返回。

GDScriptC#

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 🔗

返回由从 0 开始的 idx 指示的节点名称。如果 idx 超出范围，则会生成错误。另请参阅 get_subname_count 和 get_name_count。

GDScriptC#

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”。

int get_name_count() const 🔗

返回路径中节点名称的数量。不包括属性子名称。

例如，"../RigidBody2D/Sprite2D:texture" 包含 3 个节点名称。

StringName get_subname(idx: int) const 🔗

返回由从 0 开始的 idx 指示的属性名称。如果 idx 超出范围，则会生成错误。另请参阅 get_subname_count。

GDScriptC#

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 个子名称。

int hash() const 🔗

返回代表该节点路径内容的 32 位哈希值。

注意：由于哈希冲突，具有相等哈希值的节点路径无法保证相同。不同哈希值的节点路径保证是不同的。

bool is_absolute() const 🔗

如果节点路径是绝对路径，则返回 true。与相对路径不同，绝对路径由前导斜杠字符（/）表示，并且始终从 SceneTree 开始。它可用于从根节点可靠地访问节点（例如，如果存在名为 “Global” 的自动加载，则 "/root/Global"）。

bool is_empty() const 🔗

如果节点路径是从空的 String（""）构造的，则返回 true。

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。