NodePath

预先解析的场景树路径。

描述

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

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

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

NodePath 的一些示例包括:

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

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

方法说明

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

目标节点路径后加上可选的“子名称”可以指向资源或属性,也可以嵌套。

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

# 指向精灵节点
Path2D/PathFollow2D/Sprite
# 指向 Sprite 节点及其“纹理”资源。
# get_node() 将检索“Sprite”,而 get_node_and_resource()
# 将同时检索 Sprite 节点和“纹理”资源。
Path2D/PathFollow2D/Sprite:texture
# 指向 Sprite 节点及其“位置”属性。
"Path2D/PathFollow2D/Sprite:position"
# 指向 Sprite 节点及其“position”属性的“x”组件。
"Path2D/PathFollow2D/Sprite:position:x"
# 绝对路径(来自“root”)
/root/Level/Path2D

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

# 会被解析为 position 节点 x 属性的节点路径
var node_path = NodePath("position:x")
# 会被解析为当前节点 position 属性 x 分量的节点路径
var property_path = node_path.get_as_property_path()
print(property_path) # :position:x

  • String get_concatenated_subnames ( )

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

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

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

var node_path = NodePath("Path2D/PathFollow2D/Sprite")
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 ( )

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

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


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

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

  • int get_subname_count ( )

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

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


  • bool is_absolute ( )

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


节点路径为空时返回 true