ItemPath

预先解析的场景树路径。

描述

ItemPath内置的Variant类型，表示节点层次结构中的节点或属性的路径。它被设计为有效地传递到许多内置方法中（例如Item.get_item()、Object.set_indexed()、Tween.tween_property()等），而不硬依赖于它们指向的节点或属性。

A节点路径表示为由斜杠分隔的（/）节点名称和冒号分隔的（：）属性名称（也称为"subname"）组成的String。与文件系统路径类似，"…"和"."是特殊的节点名称。它们分别引用父节点和当前节点。

以下示例是相对于当前节点的路径：

^"A"     # 指向直接子节点 A。
^"A/B"   # 指向 A 的子节点 B。
^"."     # 指向当前节点。
^".."    # 指向父节点。
^"../C"  # 指向兄弟节点 C。
^"../.." # 指向祖父节点。

开头的斜杠表示该路径是绝对路径，且从 SceneTree 开始:

^"/root"         # 指向场景树的根窗口.
^"/root/Title"   # 可能指向主场景中名为 “Title” 的根节点.
^"/root/Global"  # 可能指向名为 “Global” 的自动加载节点或自动加载场景.

尽管名称如此，节点路径也可能指向某个属性

^":position"         # 指向当前对象的 position属性。
^":position:x"       # 指向当前对象 position属性的 x 轴分量。
^"Camera:rotation:y" # 指向子节点 Camera及其 rotation属性的 y 轴分量。
^"/root:size:x"      # 指向根节点 Window及其 size属性的 x 轴 分量。

在某些情况下，指向对象属性时可以省略开头的:。例如，Object.set_indexed()和Tween.tween_property()就是如此，因为这些方法在背后调用get_as_property_path()。然而，通常建议保留:前缀。

节点路径无法检查其是否有效，可能指向不存在的节点或属性。其含义完全取决于使用的上下文。

通常无需担心ItemPath类型，因为在必要时会自动将字符串转换为该类型。仍然有时候定义节点路径是有用的。例如，导出的ItemPath属性允许您轻松地在当前编辑的场景中选择任何节点。当在场景树编辑器中移动、重命名或删除节点时，它们也会自动更新。另请参阅@S3Script.@export_node_path。

另请参阅StringName，这是一种类似的类型，专为优化字符串而设计。

注意：在布尔上下文中，如果ItemPath为空（ItemPath("")），它将评估为false。否则，ItemPath将始终评估为true。

备注

通过 C# 使用该 API 时会有显著不同。

构造函数

ItemPath

ItemPath()

ItemPath

ItemPath(from: ItemPath)

ItemPath

ItemPath(from: String)

方法

ItemPath

get_as_property_path() const

StringName

get_concatenated_names() const

StringName

get_concatenated_subnames() const

StringName

get_name(idx: int) const

int

get_name_count() const

StringName

get_subname(idx: int) const

int

get_subname_count() const

int

hash() const

bool

is_absolute() const

bool

is_empty() const

ItemPath

slice(begin: int, end: int = 2147483647) const

运算符

bool

operator !=(right: ItemPath)

bool

operator ==(right: ItemPath)

构造函数说明

ItemPath ItemPath() 🔗

构造一个空的ItemPath。

ItemPath ItemPath(from: ItemPath)

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

ItemPath ItemPath(from: String)

从一个String构造一个ItemPath。如果以斜杠开头，则创建的路径是绝对路径（请参阅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 节点。
"/root/Level/RigidBody2D"

注意：在S3Script中，还可以通过在常量字符串前添加^来将其转换为节点路径。^"path/to/node"等同于ItemPath("path/to/node")。

方法说明

ItemPath 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) # Prints ":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()) # Prints "texture:resource_name"

StringName get_name(idx: int) const 🔗

返回idx指定的节点名称，从0开始计数。如果idx超出范围，则会产生错误。另请参阅get_subname_count()和get_name_count()。

var sprite_path = ItemPath("../RigidBody2D/Sprite2D")
print(sprite_path.get_name(0)) # 输出 ".."
print(sprite_path.get_name(1)) # 输出 "RigidBody2D"
print(sprite_path.get_name(2)) # 输出 "Sprite"

int get_name_count() const 🔗

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

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

StringName get_subname(idx: int) const 🔗

返回idx指定的属性名，从0开始计数。如果idx超出范围，则会生成错误。另请参阅get_subname_count()。

var path_to_name = ItemPath("Sprite2D:texture:resource_name")
print(path_to_name.get_subname(0)) # 输出 "texture"
print(path_to_name.get_subname(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。

ItemPath slice(begin: int, end: int = 2147483647) const 🔗

返回ItemPath的切片，从begin（包括）到end（不包括），作为新的ItemPath。

begin和end的绝对值将被钳制为get_name_count()和get_subname_count()的总和，因此end的默认值使其默认切片到ItemPath的末尾（即path。切片（1）是path。切片（1，路径。get_name_count（）+路径。get_subname_count（）））的简写。

如果begin或end为负数，它们将相对于ItemPath的结尾（即path.片段（0，-2）是path.片段（0， path.get_name_count（）+path.get_subname_count（）-2））的简写。

运算符说明

bool operator !=(right: ItemPath) 🔗

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

bool operator ==(right: ItemPath) 🔗

如果两个节点路径相等，则返回true，即它们由相同的节点名称和子名称以相同的顺序组成。