Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

NodePath

预先解析的场景树路径。

描述

场景树中预先解析的相对或绝对路径,用于 Node.get_node 和类似函数。它可以引用节点、节点内的资源、或节点或资源的属性。例如,"Path2D/PathFollow2D/Sprite2D:texture:size" 将引用名为 "Sprite2D" 节点上的 texture 资源的 size 属性,该节点是路径中其他命名节点的一个子节点。

通常只需将一个字符串传递给 Node.get_node,它将会被自动转换,但可能偶尔想要使用 NodePath 或文字语法 ^"path" 提前解析路径。导出 NodePath 变量会在编辑器的属性面板中,为你提供一个节点选择小部件,这通常很有用。

NodePath 由斜线分隔的节点名称列表(如文件系统路径)和可选的冒号分隔的“子名称”列表组成,这些“子名称”可以是资源或属性。

NodePath 的一些示例包括:

# 没有前导斜杠意味着它是相对于当前节点的。
^"A" # 直接子节点 A
^"A/B" # A 的子节点 B
^"." # 当前节点。
^".." # 父节点。
^"../C" # 兄弟节点 C。
^"../.." # 祖父节点。
# 前导斜杠意味着它是来自 SceneTree 的绝对路径。
^"/root" # 等同于 get_tree().get_root()。
^"/root/Main" # 如果你的主场景的根节点被命名为“Main”。
^"/root/MyAutoload" # 如果你有一个自动加载的节点或场景。

另见 StringName,它是通用字符串的类似概念。

注意:在编辑器中,NodePath 属性在场景树中移动、重命名或删除节点时会自动更新,但它们不会在运行时更新。

注意:在布尔上下文中,如果 NodePath 为空(NodePath("")),则它将评估为 false。否则,NodePath 将始终评估为 true

备注

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

教程

构造函数

NodePath

NodePath ( )

NodePath

NodePath ( NodePath from )

NodePath

NodePath ( String from )

方法

NodePath

get_as_property_path ( ) const

StringName

get_concatenated_names ( ) const

StringName

get_concatenated_subnames ( ) const

StringName

get_name ( int idx ) const

int

get_name_count ( ) const

StringName

get_subname ( int idx ) const

int

get_subname_count ( ) const

int

hash ( ) const

bool

is_absolute ( ) const

bool

is_empty ( ) const

操作符

bool

operator != ( NodePath right )

bool

operator == ( NodePath right )


构造函数说明

NodePath NodePath ( )

构造空的 NodePath


NodePath NodePath ( NodePath from )

构造给定 NodePath 的副本。NodePath("example") 等价于 ^"example"


NodePath NodePath ( String from )

从一个字符串,例如 "Path2D/PathFollow2D/Sprite2D:texture:size",创建一个 NodePath。如果路径以斜杠开头,则该路径是绝对路径。绝对路径仅在全局场景树中有效,在单个场景中无效。在相对路径中,"."".." 表示当前节点及其父节点。

在到目标节点的路径后可以选择包含“子名称”,它可以指向资源或属性,也可以被嵌套。

有效 NodePath 的示例(假设这些节点存在,并具有引用的资源或属性):

# 指向 Sprite2D 节点。
"Path2D/PathFollow2D/Sprite2D"
# 指向 Sprite2D 节点及其“纹理(texture)”资源。
# get_node() 将检索“Sprite2D”,而 get_node_and_resource()
# 将同时检索该 Sprite2D 节点和其“纹理(texture)”资源。
"Path2D/PathFollow2D/Sprite2D:texture"
# 指向 Sprite2D 节点及其“位置(position)”属性。
"Path2D/PathFollow2D/Sprite2D:position"
# 指向 Sprite2D 节点及其“位置(position)”属性的“x”分量。
"Path2D/PathFollow2D/Sprite2D:position:x"
# 绝对路径(从 “root” 开始)
/root/Level/Path2D

方法说明

NodePath get_as_property_path ( ) const

返回前面带有冒号字符(:)的节点路径,将其转换为没有节点名称的纯属性路径(默认为从当前节点解析)。

# 这将被解析为一个到“position”节点中“x”属性的节点路径。
var node_path = NodePath("position:x")
# 这将被解析为一个到当前节点中“position”属性的“x”分量的节点路径。
var property_path = node_path.get_as_property_path()
print(property_path) # :position:x

StringName get_concatenated_names ( ) const

返回所有以斜杠字符(/)作为分隔符连接的且不带子名称的路径。


StringName get_concatenated_subnames ( ) const

返回所有以冒号字符(:)作为分隔符连接的子名称,即节点路径中第一个冒号的右侧。

var node_path = NodePath("Path2D/PathFollow2D/Sprite2D:texture:load_path")
print(node_path.get_concatenated_subnames()) # texture:load_path

StringName get_name ( int idx ) const

获取由 idx(0 到 get_name_count - 1)指示的节点名称。

var node_path = NodePath("Path2D/PathFollow2D/Sprite2D")
print(node_path.get_name(0)) # Path2D
print(node_path.get_name(1)) # PathFollow2D
print(node_path.get_name(2)) # Sprite

int get_name_count ( ) const

获取组成路径的节点名称的数量。不包括子名称(见 get_subname_count)。

例如,"Path2D/PathFollow2D/Sprite2D" 中有 3 个名称。


StringName get_subname ( int idx ) const

获取由 idx 表示的资源或属性名称(0 到 get_subname_count - 1)。

var node_path = NodePath("Path2D/PathFollow2D/Sprite2D:texture:load_path")
print(node_path.get_subname(0)) # texture
print(node_path.get_subname(1)) # load_path

int get_subname_count ( ) const

获取路径中资源或属性名称(“子名称”)的数量。每个子名称都列在节点路径中的冒号字符(:)之后。

例如,"Path2D/PathFollow2D/Sprite2D:texture:load_path" 中有 2 个子名称。


int hash ( ) const

返回代表该 NodePath 内容的 32 位哈希值。


bool is_absolute ( ) const

如果节点路径是绝对的(而不是相对的),即以斜线字符(/)开始,返回 true。绝对节点路径可以用来访问根节点("/root")或自动加载(例如"/global" 如果注册了一个叫“global”的自动加载项)。


bool is_empty ( ) const

如果节点路径为空,则返回 true


操作符说明

bool operator != ( NodePath right )

如果两个节点路径不相等,则返回 true


bool operator == ( NodePath right )

如果两个节点路径相等,即路径中的所有节点名称都相同且顺序一致,则返回 true