使用指南
Cocos 节点 / 组件节点
Cocos 节点 / 组件 节点手册，包含 8 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
操作场景中的 Node 对象，包括层级、变换、组件、激活状态和场景查找。
覆盖范围
- 节点数量：8
- 分类路径：Cocos 节点 / 组件
典型使用场景
- 动态创建、查找、移动或销毁节点
- 控制节点位置、旋转、缩放和可见性
- 获取或添加组件后继续调用组件节点
通用注意事项
- 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
- 销毁节点后不要继续使用旧引用。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 按路径查找组件 | nodeFindComponentByPath | 4 / 4 | 立即继续 |
| 递归查找全部同名节点组件 | nodeFindAllComponentsByNameRecursive | 4 / 2 | 立即继续 |
| 递归查找首个同名节点组件 | nodeFindFirstComponentByNameRecursive | 4 / 4 | 立即继续 |
| 获取组件 | nodeGetComponentByName | 3 / 4 | 立即继续 |
| 获取组件列表 | nodeGetComponentsByName | 3 / 3 | 立即继续 |
| 添加组件 | nodeAddComponentByName | 3 / 3 | 立即继续 |
| 子树全部组件 | nodeGetComponentsInChildrenByName | 3 / 3 | 立即继续 |
| 子树首个组件 | nodeGetComponentInChildrenByName | 3 / 4 | 立即继续 |
按路径查找组件
按路径查找组件：先从当前激活场景根节点，或你显式传入的根节点开始按路径定位节点，再检查该节点本体是否挂载目标组件。 它不会扩张成“查整个子树组件”，适合你已知场景路径且只关心目标节点自身组件的场景。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | nodeFindComponentByPath |
| 分类 | Cocos 节点 |
| 二级分类 | 组件 |
| 分组 | - |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 触发按路径查找组件。 | - | 可选 |
root | 根节点 | 数据 | cc.Node | 查询起点 留空时默认使用当前激活场景根节点；连接后，路径会相对这个根节点解释。 | - | 可选 |
path | 路径 | 数据 | string | 相对路径 始终相对根节点解释，例如 Canvas/Player/Weapon。 | 可编辑控件 默认值："" 可从项目内容中选择 | 必填 |
className | 组件名 | 数据 | string | 目标组件类名 只检查命中节点本体上的该组件，不会继续扩张到它的子节点。 | 可编辑控件 默认值："" 可从项目内容中选择 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 路径组件查找结束后继续执行。 | - | 可选 |
component | 组件 | 数据 | cc.Component | 命中的组件 目标节点本体上的组件；未命中时返回 null。 | - | 可选 |
node | 节点 | 数据 | cc.Node | 命中的节点 按路径定位到的节点；就算组件不存在，也会把节点本身透传出来。 | - | 可选 |
found | 是否找到 | 数据 | boolean | 是否命中组件 只有当目标节点本体挂载了该组件时才会返回 true。 | - | 可选 |
使用场景
- 动态创建、查找、移动或销毁节点
- 控制节点位置、旋转、缩放和可见性
- 获取或添加组件后继续调用组件节点
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
- 销毁节点后不要继续使用旧引用。
递归查找全部同名节点组件
递归查找全部同名节点组件：先按深度优先顺序收集全部同名节点，再依次检查这些节点本体上的目标组件。 只有真正挂载了目标组件的节点才会进入结果数组；不会自动扩张为 getComponentsInChildren。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | nodeFindAllComponentsByNameRecursive |
| 分类 | Cocos 节点 |
| 二级分类 | 组件 |
| 分组 | - |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 触发递归查找全部同名节点组件。 | - | 可选 |
root | 根节点 | 数据 | cc.Node | 查询起点 留空时默认从当前激活场景根节点开始递归查找。 | - | 可选 |
name | 名称 | 数据 | string | 节点名称 按完全相同的名称做递归匹配，大小写敏感。 | 输入框 默认值："" | 必填 |
className | 组件名 | 数据 | string | 目标组件类名 只检查每个命中节点本体上的该组件，不会继续扩张到它们的子节点。 | 可编辑控件 默认值："" 可从项目内容中选择 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 组件列表收集结束后继续执行。 | - | 可选 |
components | 组件列表 | 数据 | cc.Component / array | 命中组件列表 按节点深度优先命中顺序返回全部组件；未命中时返回空数组。 | - | 可选 |
使用场景
- 动态创建、查找、移动或销毁节点
- 控制节点位置、旋转、缩放和可见性
- 获取或添加组件后继续调用组件节点
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
- 销毁节点后不要继续使用旧引用。
递归查找首个同名节点组件
递归查找首个同名节点组件：先按深度优先顺序找到首个同名节点，再检查该节点本体是否挂载目标组件。 如果该节点本体没有目标组件，即使它的子节点有，也不会继续扩张为子树组件搜索。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | nodeFindFirstComponentByNameRecursive |
| 分类 | Cocos 节点 |
| 二级分类 | 组件 |
| 分组 | - |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 触发递归查找首个同名节点组件。 | - | 可选 |
root | 根节点 | 数据 | cc.Node | 查询起点 留空时默认从当前激活场景根节点开始递归查找。 | - | 可选 |
name | 名称 | 数据 | string | 节点名称 按完全相同的名称做递归匹配，大小写敏感。 | 输入框 默认值："" | 必填 |
className | 组件名 | 数据 | string | 目标组件类名 只检查首个命中节点本体上的该组件，不会继续扩张到它的子节点。 | 可编辑控件 默认值："" 可从项目内容中选择 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 首个组件查找结束后继续执行。 | - | 可选 |
component | 组件 | 数据 | cc.Component | 命中的组件 首个同名节点本体上的组件；未命中时返回 null。 | - | 可选 |
node | 节点 | 数据 | cc.Node | 首个命中节点 按名称递归找到的首个节点；就算组件不存在，也会把节点本身透传出来。 | - | 可选 |
found | 是否找到 | 数据 | boolean | 是否命中组件 只有当首个命中节点本体挂载了该组件时才会返回 true。 | - | 可选 |
使用场景
- 动态创建、查找、移动或销毁节点
- 控制节点位置、旋转、缩放和可见性
- 获取或添加组件后继续调用组件节点
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
- 销毁节点后不要继续使用旧引用。
获取组件
获取组件：按组件名获取节点上的组件。 适合游戏运行时获取其他组件来调用其方法，例如获取Sprite组件修改图片。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | nodeGetComponentByName |
| 分类 | Cocos 节点 |
| 二级分类 | 组件 |
| 分组 | - |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 触发获取组件 | - | 可选 |
node | 节点 | 数据 | cc.Node | 目标节点 要获取组件的节点 | - | 必填 |
className | 组件名 | 数据 | string | 组件类名 要获取的组件名称 | 可编辑控件 默认值："" 可从项目内容中选择 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 获取完成后继续执行 | - | 可选 |
component | 组件 | 数据 | cc.Component | 找到的组件 找到的组件（可能为null） | - | 可选 |
found | 是否找到 | 数据 | boolean | 是否找到 是否成功找到组件 | - | 可选 |
node | 节点 | 数据 | cc.Node | 目标节点 要获取组件的节点 | - | 可选 |
使用场景
- 动态创建、查找、移动或销毁节点
- 控制节点位置、旋转、缩放和可见性
- 获取或添加组件后继续调用组件节点
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
- 销毁节点后不要继续使用旧引用。
获取组件列表
获取组件列表：获取同一节点上指定组件名的所有组件。 返回组件数组，可能为空数组。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | nodeGetComponentsByName |
| 分类 | Cocos 节点 |
| 二级分类 | 组件 |
| 分组 | - |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 触发获取组件列表 | - | 可选 |
node | 节点 | 数据 | cc.Node | 目标节点 要获取组件的节点 | - | 必填 |
className | 组件名 | 数据 | string | 组件类名 要获取的组件名称 | 可编辑控件 默认值："" 可从项目内容中选择 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 获取完成后继续执行 | - | 可选 |
components | 组件列表 | 数据 | cc.Component / array | 组件数组 找到的所有组件 | - | 可选 |
node | 节点 | 数据 | cc.Node | 目标节点 要获取组件的节点 | - | 可选 |
使用场景
- 动态创建、查找、移动或销毁节点
- 控制节点位置、旋转、缩放和可见性
- 获取或添加组件后继续调用组件节点
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
- 销毁节点后不要继续使用旧引用。
添加组件
添加组件：按组件名在节点上添加组件。 适合游戏运行时动态给角色添加音效、动画等组件。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | nodeAddComponentByName |
| 分类 | Cocos 节点 |
| 二级分类 | 组件 |
| 分组 | - |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 触发添加组件 | - | 可选 |
node | 节点 | 数据 | cc.Node | 目标节点 要添加组件的节点 | - | 必填 |
className | 组件名 | 数据 | string | 组件类名 要添加的组件名称 | 可编辑控件 默认值："" 可从项目内容中选择 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 添加完成后继续执行 | - | 可选 |
component | 组件 | 数据 | cc.Component | 新创建的组件 新创建的组件实例 | - | 可选 |
node | 节点 | 数据 | cc.Node | 目标节点 要添加组件的节点 | - | 可选 |
使用场景
- 动态创建、查找、移动或销毁节点
- 控制节点位置、旋转、缩放和可见性
- 获取或添加组件后继续调用组件节点
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
- 销毁节点后不要继续使用旧引用。
子树全部组件
子树全部组件：获取节点及其子节点中所有匹配的组件。 适合遍历场景中某类组件的所有实例。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | nodeGetComponentsInChildrenByName |
| 分类 | Cocos 节点 |
| 二级分类 | 组件 |
| 分组 | - |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 触发获取子树组件列表 | - | 可选 |
node | 节点 | 数据 | cc.Node | 根节点 要搜索的根节点 | - | 必填 |
className | 组件名 | 数据 | string | 组件类名 要查找的组件名称 | 可编辑控件 默认值："" 可从项目内容中选择 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 获取完成后继续执行 | - | 可选 |
components | 组件列表 | 数据 | cc.Component / array | 组件数组 找到的所有组件 | - | 可选 |
node | 节点 | 数据 | cc.Node | 根节点 要搜索的根节点 | - | 可选 |
使用场景
- 动态创建、查找、移动或销毁节点
- 控制节点位置、旋转、缩放和可见性
- 获取或添加组件后继续调用组件节点
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
- 销毁节点后不要继续使用旧引用。
子树首个组件
子树首个组件：在节点及其子节点中查找首个匹配组件。 适合在角色及其装备上查找特定组件。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | nodeGetComponentInChildrenByName |
| 分类 | Cocos 节点 |
| 二级分类 | 组件 |
| 分组 | - |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 触发获取子树组件 | - | 可选 |
node | 节点 | 数据 | cc.Node | 根节点 要搜索的根节点 | - | 必填 |
className | 组件名 | 数据 | string | 组件类名 要查找的组件名称 | 可编辑控件 默认值："" 可从项目内容中选择 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 获取完成后继续执行 | - | 可选 |
component | 组件 | 数据 | cc.Component | 找到的组件 找到的组件（可能为null） | - | 可选 |
found | 是否找到 | 数据 | boolean | 是否找到 是否成功找到组件 | - | 可选 |
node | 节点 | 数据 | cc.Node | 根节点 要搜索的根节点 | - | 可选 |
使用场景
- 动态创建、查找、移动或销毁节点
- 控制节点位置、旋转、缩放和可见性
- 获取或添加组件后继续调用组件节点
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 节点路径查找依赖场景层级，改名或移动节点后要同步检查。
- 销毁节点后不要继续使用旧引用。