Cocos 节点 / 层级节点

学习目标

操作场景中的 Node 对象，包括层级、变换、组件、激活状态和场景查找。

覆盖范围

• 节点数量：17
• 分类路径：Cocos 节点 / 层级

典型使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

通用注意事项

• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

节点索引

节点	节点 ID	输入/输出	执行方式
按路径查找节点	nodeFindByPath	3 / 3	立即继续
按名称获取子节点	nodeGetChildByName	2 / 2	立即继续
插入子节点	nodeInsertChild	4 / 2	立即继续
从父节点移除自身	nodeRemoveFromParent	2 / 2	立即继续
递归查找全部同名节点	nodeFindAllByNameRecursive	3 / 2	立即继续
递归查找首个同名节点	nodeFindFirstByNameRecursive	3 / 3	立即继续
获取层级路径	nodeGetPathInHierarchy	1 / 1	立即继续
获取当前激活场景根节点	nodeGetSceneRoot	1 / 2	立即继续
获取父节点	nodeGetParent	1 / 1	立即继续
获取同级序号	nodeGetSiblingIndex	1 / 1	立即继续
获取子节点列表	nodeGetChildren	1 / 1	立即继续
判断是否为某节点子树成员	nodeIsChildOf	2 / 1	立即继续
设置父节点	nodeSetParent	4 / 2	立即继续
设置同级序号	nodeSetSiblingIndex	3 / 2	立即继续
添加子节点	nodeAddChild	3 / 2	立即继续
移除所有子节点	nodeRemoveAllChildren	2 / 2	立即继续
移除指定子节点	nodeRemoveChild	3 / 2	立即继续

按路径查找节点

按路径查找节点：从当前激活场景根节点，或你显式传入的根节点开始，按层级路径查找目标节点。 path 始终相对 root 解释；如果 root 未连接，就默认相对当前场景根节点。

节点信息

字段	值
节点 ID	nodeFindByPath
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口 触发按路径查找节点。	-	可选
root	根节点	数据	cc.Node	查询起点 留空时默认使用当前激活场景根节点；连接后，路径会相对这个根节点解释。	-	可选
path	路径	数据	string	相对路径 始终相对根节点解释，例如 Canvas/Player/Weapon。	可编辑控件 默认值："" 可从项目内容中选择	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成 路径查找结束后继续执行。	-	可选
node	节点	数据	cc.Node	命中的节点 按路径找到的节点；未命中时返回 null。	-	可选
found	是否找到	数据	boolean	是否命中 路径查找是否成功命中节点。	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

按名称获取子节点

按名称获取子节点：按名称查找直接子节点。 只查找直接子节点，适合快速定位指定的子对象，如获取角色身上的”武器”子节点。

节点信息

字段	值
节点 ID	nodeGetChildByName
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
node	节点	数据	cc.Node	目标父节点 要在其中查找子节点的父节点	-	必填
name	名称	数据	string	子节点名称 要查找的子节点名称	输入框 默认值：""	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
child	子节点	数据	cc.Node	找到的子节点 找到的子节点（可能为null）	-	可选
found	是否找到	数据	boolean	是否找到 是否成功找到子节点	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

插入子节点

插入子节点：把子节点插入到指定序号位置。 适合控制子节点的绘制顺序或层级排列。

节点信息

字段	值
节点 ID	nodeInsertChild
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口 触发插入子节点	-	可选
parent	父节点	数据	cc.Node	目标父节点 要插入子节点的父节点	-	必填
child	子节点	数据	cc.Node	要插入的子节点 要插入的子节点	-	必填
index	同级序号	数据	number	插入位置 要插入的同级序号位置	输入框 默认值：0	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成 插入完成后继续执行	-	可选
parent	父节点	数据	cc.Node	目标父节点 要插入子节点的父节点	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

从父节点移除自身

从父节点移除自身：将节点从当前父节点移除。 节点不会被销毁，只是脱离父子关系。

节点信息

字段	值
节点 ID	nodeRemoveFromParent
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口 触发移除操作	-	可选
node	节点	数据	cc.Node	目标节点 要从父节点移除的节点	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成 移除完成后继续执行	-	可选
node	节点	数据	cc.Node	目标节点 要从父节点移除的节点	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

递归查找全部同名节点

递归查找全部同名节点：从当前激活场景根节点，或你显式传入的根节点开始，按深度优先顺序收集所有名称完全相同的节点。 适合一次性拿到多个同名刷怪点、挂点或容器节点。

节点信息

字段	值
节点 ID	nodeFindAllByNameRecursive
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口 触发递归收集同名节点。	-	可选
root	根节点	数据	cc.Node	查询起点 留空时默认从当前激活场景根节点开始递归查找。	-	可选
name	名称	数据	string	节点名称 按完全相同的名称做递归匹配，大小写敏感。	输入框 默认值：""	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成 递归节点收集结束后继续执行。	-	可选
nodes	节点列表	数据	cc.Node / array	命中节点列表 按深度优先顺序返回全部同名节点；未命中时返回空数组。	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

递归查找首个同名节点

递归查找首个同名节点：从当前激活场景根节点，或你显式传入的根节点开始，按深度优先顺序查找首个名称完全相同的节点。 适合“我只知道节点名，但不知道它在场景树哪里”的场景。

节点信息

字段	值
节点 ID	nodeFindFirstByNameRecursive
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口 触发递归名称查找。	-	可选
root	根节点	数据	cc.Node	查询起点 留空时默认从当前激活场景根节点开始递归查找。	-	可选
name	名称	数据	string	节点名称 按完全相同的名称做递归匹配，大小写敏感。	输入框 默认值：""	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成 递归名称查找结束后继续执行。	-	可选
node	节点	数据	cc.Node	首个命中节点 按深度优先顺序找到的首个同名节点；未命中时返回 null。	-	可选
found	是否找到	数据	boolean	是否命中 递归名称查找是否成功命中节点。	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

获取层级路径

获取层级路径：获取节点在层级中的路径。 常用于日志与定位，例如 Canvas/Player/Weapon。

节点信息

字段	值
节点 ID	nodeGetPathInHierarchy
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
node	节点	数据	cc.Node	目标节点 要获取层级路径的节点	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
path	层级路径	数据	string	层级路径 例如Canvas/Player/Weapon	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

获取当前激活场景根节点

获取当前激活场景根节点：返回 Director 当前正在运行的场景根节点。 它通常作为场景树查询的默认起点，适合配合“按路径查找节点”或“递归查找同名节点”使用。

节点信息

字段	值
节点 ID	nodeGetSceneRoot
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口 触发获取当前激活场景根节点。	-	可选

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成 场景根节点输出后继续执行。	-	可选
node	节点	数据	cc.Node	场景根节点 当前激活场景的根节点。可作为场景树查询的默认起点。	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

获取父节点

获取父节点：获取节点的父节点。 如果节点没有父节点（根节点），返回null。

节点信息

字段	值
节点 ID	nodeGetParent
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
node	节点	数据	cc.Node	目标节点 要获取父节点的节点	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
parent	父节点	数据	cc.Node	父节点 节点的父节点（可能为null）	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

获取同级序号

获取同级序号：返回节点在父节点子列表中的序号。 用于确定子节点间的叠放次序。

节点信息

字段	值
节点 ID	nodeGetSiblingIndex
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
node	节点	数据	cc.Node	目标节点 要获取同级序号的节点	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
index	同级序号	数据	number	同级索引 节点在父节点子列表中的索引	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

获取子节点列表

获取子节点列表：获取节点的所有直接子节点。 适合遍历子对象，例如背包物品列表、敌人编队等。

节点信息

字段	值
节点 ID	nodeGetChildren
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
node	节点	数据	cc.Node	目标节点 要获取子节点的节点	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
children	子节点列表	数据	cc.Node / array	子节点数组 节点的所有直接子节点	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

判断是否为某节点子树成员

判断是否为某节点子树成员：判断节点是否在目标父节点的子树中。 递归检查整个层级树，适合判断某个对象是否属于某个容器。

节点信息

字段	值
节点 ID	nodeIsChildOf
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
node	节点	数据	cc.Node	要判断的节点 要检查的节点	-	必填
parent	父节点	数据	cc.Node	目标父节点 要检查的目标父节点	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
isChildOf	是否子树成员	数据	boolean	是否子树成员 结果为true：在目标父节点的子树中	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

设置父节点

设置父节点：将节点重新挂到目标父节点下。 适合实现角色换装、物品跟随等效果。

节点信息

字段	值
节点 ID	nodeSetParent
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口 触发设置父节点	-	可选
node	节点	数据	cc.Node	要改父节点的节点 要重新设置父节点的节点	-	必填
parent	父节点	数据	cc.Node	新父节点 新的父节点（允许为空，表示脱离父节点）	-	可选
keepWorldTransform	保持世界变换	数据	boolean	保持世界变换 true：尽量保持世界坐标/旋转/缩放不变	开关 默认值：false	可选

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成 设置完成后继续执行	-	可选
node	节点	数据	cc.Node	要改父节点的节点 要重新设置父节点的节点	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

设置同级序号

设置同级序号：调整节点在同级子节点中的前后顺序。 适合改变UI元素的叠放层次。

节点信息

字段	值
节点 ID	nodeSetSiblingIndex
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口 触发设置同级序号	-	可选
node	节点	数据	cc.Node	目标节点 要设置同级序号的节点	-	必填
index	同级序号	数据	number	新索引 要设置的同级序号	输入框 默认值：0	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成 设置完成后继续执行	-	可选
node	节点	数据	cc.Node	目标节点 要设置同级序号的节点	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

添加子节点

添加子节点：将一个节点添加为指定父节点的子节点。 如果该节点已有父节点，会先自动移除旧关系。

节点信息

字段	值
节点 ID	nodeAddChild
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口 触发添加子节点	-	可选
parent	父节点	数据	cc.Node	目标父节点 要添加子节点的父节点	-	必填
child	子节点	数据	cc.Node	要添加的子节点 要添加的子节点	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成 添加完成后继续执行	-	可选
parent	父节点	数据	cc.Node	目标父节点 要添加子节点的父节点	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

移除所有子节点

移除所有子节点：移除当前节点的所有子节点。 注意：不会销毁子节点，只是移除父子关系。

节点信息

字段	值
节点 ID	nodeRemoveAllChildren
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口 触发移除所有子节点	-	可选
node	节点	数据	cc.Node	目标节点 要移除其所有子节点的节点	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成 移除完成后继续执行	-	可选
node	节点	数据	cc.Node	目标节点 要移除其所有子节点的节点	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。

---

移除指定子节点

移除指定子节点：从父节点移除指定的子节点。 子节点不会被销毁，只是脱离父子关系。

节点信息

字段	值
节点 ID	nodeRemoveChild
分类	Cocos 节点
二级分类	层级
分组	-
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口 触发移除子节点	-	可选
parent	父节点	数据	cc.Node	目标父节点 要从中移除子节点的父节点	-	必填
child	子节点	数据	cc.Node	要移除的子节点 要移除的子节点	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成 移除完成后继续执行	-	可选
parent	父节点	数据	cc.Node	目标父节点 要从中移除子节点的父节点	-	可选

使用场景

• 动态创建、查找、移动或销毁节点
• 控制节点位置、旋转、缩放和可见性
• 获取或添加组件后继续调用组件节点

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
• 销毁节点后不要继续使用旧引用。