Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
NodePath
一個預先解析的場景樹路徑。
說明
NodePath 這個內建 Variant 類型用來表示節點階層中指向某節點或屬性的路徑。它設計成能有效率地傳遞給許多內建方法（例如 Node.get_node()、Object.set_indexed()、Tween.tween_property() 等），而不需直接依賴所指向的節點或屬性。
節點路徑以由斜線（/）分隔的節點名稱，以及冒號（:）分隔的屬性名稱（也稱為「子名稱」）組成的 String 來表示。類似檔案系統路徑，特殊節點名稱 ".." 和 "." 分別代表父節點和當前節點。
以下範例為相對於當前節點的路徑：
^"A" # 指向直接子節點 A。
^"A/B" # 指向 A 的子節點 B。
^"." # 指向目前節點。
^".." # 指向父節點。
^"../C" # 指向兄弟節點 C。
^"../.." # 指向祖父節點。
開頭有斜線則代表絕對路徑，從 SceneTree 開始：
^"/root" # 指向 SceneTree 的根視窗。
^"/root/Title" # 可能指向主場景的根節點 "Title"。
^"/root/Global" # 可能指向自動載入的節點或場景 "Global"。
節點路徑也可以指向屬性：
^":position" # 指向此物件的位置屬性。
^":position:x" # 指向此物件位置屬性的 x 軸。
^"Camera3D:rotation:y" # 指向子節點 Camera3D 及其 y 軸旋轉。
^"/root:size:x" # 指向根視窗的寬度。
在某些情況下，指向物件屬性時可以省略開頭的 :，例如 Object.set_indexed() 與 Tween.tween_property()，這些方法會呼叫 get_as_property_path()。不過，一般建議保留 : 前綴。
節點路徑無法檢查自身是否有效，也可能指向不存在的節點或屬性，其意義完全取決於使用時的上下文。
通常你不需特別處理 NodePath 類型，因為字串會在需要時自動轉換成此類型。不過在某些情境下自行設定節點路徑很方便，例如匯出的 NodePath 屬性讓你可以輕鬆在目前編輯的場景中選擇任一節點。當你在場景樹編輯器移動、重新命名或刪除節點時，這些路徑也會自動更新。另見 @GDScript.@export_node_path。
另可參考 StringName，這是一種設計用來優化字串操作的類型。
注意： 在布林判斷式中，若 NodePath 為空（NodePath("")），值為 false，否則一律為 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(from: String)
從 String 建立一個 NodePath。如果字串開頭有斜線則為絕對路徑（見 is_absolute()）。
在路徑後方可選擇性地加上「子名稱」（subnames），用來指向屬性，也可多層嵌套。
以下這些字串都是有效的節點路徑：
# 指向 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"
# 絕對路徑（自 SceneTree 起始）指向 RigidBody2D 節點。
"/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 指向目前節點的 "position" 屬性的 "x"。
var property_path = node_path.get_as_property_path()
print(property_path) # 輸出 ":position:x"
// nodePath 指向名為 "position" 的子節點的 "x" 屬性。
var nodePath = new NodePath("position:x");
// propertyPath 指向目前節點的 "position" 屬性的 "x"。
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 🔗
返回第 idx（從 0 開始）個節點名稱。如果 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)) # 輸出 "Sprite2D"
var spritePath = new NodePath("../RigidBody2D/Sprite2D");
GD.Print(spritePath.GetName(0)); // 輸出 ".."
GD.Print(spritePath.GetName(1)); // 輸出 "RigidBody2D"
GD.Print(spritePath.GetName(2)); // 輸出 "Sprite2D"
返回路徑中的節點名稱數量，不包含屬性子名稱。
例如，"../RigidBody2D/Sprite2D:texture" 中有 3 個節點名稱。
StringName get_subname(idx: int) const 🔗
返回第 idx（從 0 開始）個屬性名稱（子名稱）。如果 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 位元雜湊值。
注意： 由於雜湊碰撞，相同雜湊值的節點路徑不一定相同，但不同雜湊值的節點路徑一定不同。
如果節點路徑是絕對路徑（以斜線字元 / 開頭，且總是從 SceneTree 起始），則返回 true。這類路徑可用於從根節點可靠地存取其他節點（例如若存在名為 "Global" 的自動載入項，則 "/root/Global"）。
如果節點路徑是由空字串（""）建立，則返回 true。
NodePath slice(begin: int, end: int = 2147483647) const 🔗
傳回 NodePath 從 begin（包含）到 end（不包含）的切片，結果為新的 NodePath。
begin 和 end 的絕對值會限制在 get_name_count() 與 get_subname_count() 的總和範圍內，因此 end 的預設值會讓切片到路徑結尾（如 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。