NodePath
预先解析的场景树路径。
描述
NodePath 即“节点路径”，是一种内置的 Variant 类型，代表节点层次结构中指向某个节点或属性的路径。可以用来将路径高效地传递给许多内置方法（例如 Node.get_node()、Object.set_indexed()、Tween.tween_property() 等），实现与被指向的节点或属性的解耦。
节点的路径可以用 String 来表示，其中包含了由斜杠（/）分隔的节点名称以及由英文冒号（:）分隔的属性名称（也叫“子名称”）。与文件系统路径类似，".." 和 "." 都是特殊的节点名称，分别指向父节点和当前节点。
以下示例都是相对于当前节点的路径：
^"A" # 指向直接子节点 A。
^"A/B" # 指向 A 的子节点 B。
^"." # 指向当前节点。
^".." # 指向父节点。
^"../C" # 指向同级节点 C。
^"../.." # 指向祖父节点。
以斜杠开头的路径是绝对路径，路径从 SceneTree 开始：
^"/root" # 指向 SceneTree 的根 Window。
^"/root/Title" # 可能指向主场景的根节点，名叫“Title”。
^"/root/Global" # 可能指向名叫“Global”的自动加载节点或场景。
虽然名字里说的是“节点”，但是节点路径也可以指向属性：
^":position" # 指向该对象的位置。
^":position:x" # 指向该对象在 X 轴的位置。
^"Camera3D:rotation:y" # 指向 Camera3D 子节点及其 Y 轴旋转。
^"/root:size:x" # 指向根 Window 及其宽度。
在某些情况下，指向对象属性时可以省略前导 :。例如，Object.set_indexed() 和 Tween.tween_property() 就是这种情况，因为这些方法在后台调用 get_as_property_path()。但是，通常建议保留 : 前缀。
节点路径无法检查自身的有效性，可能指向不存在的节点或属性。具体含义完全由使用场合决定。
通常无需关心 NodePath 类型，字符串会在必要时自动转换为这个类型。但在某些情况下也会需要定义节点路径。例如利用导出的 NodePath 属性可以很方便地在当前编辑的场景中选择节点。场景树编辑器中节点发生移动、重命名、删除时，节点路径也会自动更新。另见 @GDScript.@export_node_path。
另见 StringName，这是一种针对字符串优化的相似的类型。
注意：在布尔环境中，NodePath 为空时取值为 false（NodePath("")）。否则 NodePath 始终为 true。
备注
通过 C# 使用该 API 时会有显著不同，详见 C# API 与 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)
从 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 🔗
返回该节点路径带有冒号字符（:）前缀的副本，将其转换为没有节点名称的纯属性路径（相对于当前节点）。
# 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 返回。
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()。
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 🔗
返回由从 0 开始的 idx 指示的属性名称。如果 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 开始。它可用于从根节点可靠地访问节点（例如，如果存在名为 “Global” 的自动加载，则 "/root/Global"）。
如果节点路径是从空的 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。