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" # Вказує на дочірній елемент 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 матиме значення false, якщо він порожній (NodePath("")). В іншому випадку NodePath завжди матиме значення true.
Примітка
Існують значні відмінності при використанні цього API із С#. Більше інформації: ref:doc_c_sharp_differences.
Посібники
Конструктори
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)
Constructs a NodePath як копія даної NodePath.
NodePath NodePath(from: String)
Створює NodePath із String. Створений шлях є абсолютним, якщо перед ним ставиться коса риска (див. is_absolute()).
«Підімена», необов’язково включені після шляху до цільового вузла, можуть вказувати на властивості, а також можуть бути вкладеними.
Наступні рядки можуть бути дійсними шляхами вузлів:
# Вказує на вузол Sprite2D.
"Level/RigidBody2D/Sprite2D"
# Вказує на вузол Sprite2D і його "текстурний" ресурс.
# get_node() отримає Sprite2D, а get_node_and_resource()
# отримає як вузол Sprite2D, так і ресурс "текстура".
"Level/RigidBody2D/Sprite2D: текстура"
# Вказує на вузол Sprite2D і його властивість "position".
"Level/RigidBody2D/Sprite2D:позиція"
# Вказує на вузол Sprite2D і компонент "x" його властивості "position".
"Level/RigidBody2D/Sprite2D:position:x"
# Вказує на вузол RigidBody2D як абсолютний шлях, що починається від SceneTree.
"/root/Level/RigidBody2D"
Примітка: У GDScript також можна перетворити постійний рядок на шлях до вузла, додавши до нього префікс ^. ^"шлях/до/вузла" еквівалентний NodePath("шлях/до/вузла").
Описи методів
NodePath get_as_property_path() const 🔗
Повертає копію шляху цього вузла з префіксом двокрапки (:), перетворюючи його на чистий шлях властивостей без імен вузла (відносно поточного вузла).
# node_path вказує на властивість "x" дочірнього вузла з назвою "position".
var node_path = ^"position:x"
# property_path вказує на «позицію» на осі «x» цього вузла.
var property_path = node_path.get_as_property_path()
print(property_path) # Виводить ":position:x"
// nodePath вказує на властивість "x" дочірнього вузла з назвою "position".
var nodePath = new NodePath("position:x");
// propertyPath вказує на "положення" на осі "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)) # Виводить "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 🔗
Повертає назву властивості, указану idx, починаючи з 0. Якщо idx виходить за межі, генерується помилка. Дивіться також get_subname_count().
var path_to_name = NodePath("Sprite2D:texture:resource_name")
print(path_to_name.get_subname(0)) # Друкує "текстуру"
print(path_to_name.get_subname(1)) # Виводить "назва_ресурсу"
var pathToName = new NodePath("Sprite2D:texture:resource_name");
GD.Print(pathToName.GetSubname(0)); // Друкує "текстуру"
GD.Print(pathToName.GetSubname(1)); // Виводить "resource_name"
int get_subname_count() const 🔗
Повертаємо кількість майнових імен ("підім'я") в доріці. Кожна підпам'я в контурі вершини перераховується після колонного символу (:).
Наприклад, "Level/RigidBody2D/Sprite2D:texture:resource_name" містить 2 підмені.
Повертає значення 32-бітного хешу, що представляє вміст вершини.
Примітка: Маршрути Node з однаковими значеннями хеш * не* гарантовано бути таким же, як наслідок зіткнень. Відсутні шляхи з різними значеннями хешу гарантовано відрізняються.
Повертає true, якщо шлях вершини абсолютний. На відміну від відносного шляху, абсолютний шлях представлений провідним символом зіткнення (/) і завжди починається з SceneTree. Він може бути використаний для надійного доступу вузлів з кореневого вузла (наприклад, "/root/Global", якщо автозавантаження названо "Global".
Повертає true, якщо шлях вершини був побудований з порожнього String (""").
NodePath slice(begin: int, end: int = 2147483647) const 🔗
Повертаємо розріз NodePath, з begin (включно) до end (виключно), як новий NodePath.
Абсолютне значення begin і end буде зафіксовано до суми get_name_count() і get_subname_count(), тому значення за замовчуванням для end встановлює кінець NodePath кінцем розрізу за замовчуванням (i.e. path.slice(1) є скороченим записом path.slice(1, path.get_name_count() + path.get_subname_count()).
Якщо ж start або end є негативними, вони будуть відносно кінця NodePath (i.e. 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, якщо два шляхи вершини рівні, тобто вони складаються з однакових імен вузлів і підnames в одному порядку.