使用指南
Cocos 组件 / UI / ToggleContainer节点
Cocos 组件 / UI / ToggleContainer 节点手册，包含 8 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。
覆盖范围
- 节点数量：8
- 分类路径：Cocos 组件 / UI / ToggleContainer
典型使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
通用注意事项
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
- 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 获取 Toggle 列表 | toggleContainerGetToggleItems | 1 / 1 | 立即继续 |
| 获取选中 Toggle | toggleContainerGetActiveToggles | 1 / 1 | 立即继续 |
| 获取允许全部取消 | toggleContainerGetAllowSwitchOff | 1 / 1 | 立即继续 |
| 设置允许全部取消 | toggleContainerSetAllowSwitchOff | 3 / 2 | 立即继续 |
| 是否有选中项 | toggleContainerAnyTogglesChecked | 1 / 1 | 立即继续 |
| 通知选中 Toggle | toggleContainerNotifyToggleCheck | 4 / 2 | 立即继续 |
| 修正组内状态 | toggleContainerEnsureValidState | 2 / 2 | 立即继续 |
| 组内选中变化事件 | toggleContainerCheckBind | 3 / 2 | 立即继续 |
获取 Toggle 列表
获取 Toggle 列表：返回 ToggleContainer 当前管理的所有 Toggle 组件。 仅首层子节点中已启用的 Toggle 会被自动纳入容器管理。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | toggleContainerGetToggleItems |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | ToggleContainer |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
toggleContainer | 开关容器 | 数据 | cc.Component / ToggleContainer | 目标开关容器 要操作的 ToggleContainer 组件 容器仅管理当前节点首层子节点中已启用的 Toggle | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
toggles | Toggle 列表 | 数据 | cc.Component / array / Toggle | Toggle 列表 容器当前管理的所有 Toggle 组件数组 仅包含首层子节点中已启用的 Toggle | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取选中 Toggle
获取选中 Toggle：返回 ToggleContainer 中当前处于选中状态的 Toggle 列表。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | toggleContainerGetActiveToggles |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | ToggleContainer |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
toggleContainer | 开关容器 | 数据 | cc.Component / ToggleContainer | 目标开关容器 要操作的 ToggleContainer 组件 容器仅管理当前节点首层子节点中已启用的 Toggle | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
toggles | 选中列表 | 数据 | cc.Component / array / Toggle | 选中 Toggle 列表 当前处于选中状态的 Toggle 组件数组 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取允许全部取消
获取允许全部取消：返回 ToggleContainer 是否允许所有选项同时取消。 值为 false 时，容器强制至少保留一个 Toggle 处于选中状态，防止出现无选中项的尴尬情况。 典型用途：单选分组（如角色选择、关卡选择）应设为 false。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | toggleContainerGetAllowSwitchOff |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | ToggleContainer |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
toggleContainer | 开关容器 | 数据 | cc.Component / ToggleContainer | 目标开关容器 要操作的 ToggleContainer 组件 容器仅管理当前节点首层子节点中已启用的 Toggle | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
allowSwitchOff | 允许全部取消 | 数据 | boolean | 允许全部取消 true=允许所有 Toggle 都不选中 false=容器会保证至少保留一个 Toggle 处于选中状态 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置允许全部取消
设置允许全部取消：控制 ToggleContainer 是否允许所有选项同时取消。 设为 false 实现单选效果（必须选中一项），设为 true 则允许多选模式中全部取消。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | toggleContainerSetAllowSwitchOff |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | ToggleContainer |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
toggleContainer | 开关容器 | 数据 | cc.Component / ToggleContainer | 目标开关容器 要操作的 ToggleContainer 组件 容器仅管理当前节点首层子节点中已启用的 Toggle | - | 必填 |
allowSwitchOff | 允许全部取消 | 数据 | boolean | 允许全部取消 true=允许所有 Toggle 都不选中 false=容器会保证至少保留一个 Toggle 处于选中状态 | 下拉选择 默认值：false | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
toggleContainer | 开关容器 | 数据 | cc.Component / ToggleContainer | 目标开关容器 要操作的 ToggleContainer 组件 容器仅管理当前节点首层子节点中已启用的 Toggle | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
是否有选中项
是否有选中项：查询 ToggleContainer 中是否存在任一处于选中状态的 Toggle。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | toggleContainerAnyTogglesChecked |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | ToggleContainer |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
toggleContainer | 开关容器 | 数据 | cc.Component / ToggleContainer | 目标开关容器 要操作的 ToggleContainer 组件 容器仅管理当前节点首层子节点中已启用的 Toggle | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
hasChecked | 有选中 | 数据 | boolean | 是否有选中项 true=至少有一个 Toggle 处于选中状态 false=全部未选中 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
通知选中 Toggle
通知选中 Toggle：显式通知 ToggleContainer 将指定 Toggle 视为当前有效选中项。 该调用会取消同组其他 Toggle 的选中状态，并将当前 toggle 视为有效选中项。 参数 emitEvent 默认为 true；当设为 false 时，仅影响其他 Toggle 取消选中时的通知方式（使用 setIsCheckedWithoutNotify），不等价于禁用容器已有 checkEvents。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | toggleContainerNotifyToggleCheck |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | ToggleContainer |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
toggleContainer | 开关容器 | 数据 | cc.Component / ToggleContainer | 目标开关容器 要操作的 ToggleContainer 组件 容器仅管理当前节点首层子节点中已启用的 Toggle | - | 必填 |
toggle | 目标开关 | 数据 | cc.Component / Toggle | 目标开关 要设为有效选中项的 Toggle 组件（必填） | - | 必填 |
emitEvent | 触发事件 | 数据 | boolean | 是否触发事件 默认 true 设为 false 时，其他 Toggle 取消选中会使用 setIsCheckedWithoutNotify，但容器自身的 checkEvents 仍会触发 | 下拉选择 默认值：true | 可选 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
toggleContainer | 开关容器 | 数据 | cc.Component / ToggleContainer | 目标开关容器 要操作的 ToggleContainer 组件 容器仅管理当前节点首层子节点中已启用的 Toggle | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
修正组内状态
修正组内状态：检查并修复 ToggleContainer 内的选中状态，确保合法。 当 allowSwitchOff=false 且当前无任何选中项时，自动选中第一个 Toggle，保证至少有一项被选中。 典型用途：动态增加或删除选项后手动校正，防止组状态异常。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | toggleContainerEnsureValidState |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | ToggleContainer |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
toggleContainer | 开关容器 | 数据 | cc.Component / ToggleContainer | 目标开关容器 要操作的 ToggleContainer 组件 容器仅管理当前节点首层子节点中已启用的 Toggle | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
toggleContainer | 开关容器 | 数据 | cc.Component / ToggleContainer | 目标开关容器 要操作的 ToggleContainer 组件 容器仅管理当前节点首层子节点中已启用的 Toggle | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
组内选中变化事件
绑定组内选中变化事件：当 ToggleContainer 中任一 Toggle 的选中状态发生变化时触发连接的 执行事件 节点。 当容器内的 Toggle 被选中或取消选中时，容器会通过 checkEvents 通知此事件。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | toggleContainerCheckBind |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | ToggleContainer |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | - | - | 可选 |
event | 事件 | 事件 | 事件 | 事件入口 连接到执行事件节点的事件输出引脚 | - | 必填 |
toggleContainer | 开关容器 | 数据 | cc.Component / ToggleContainer | 目标开关容器 要监听组内选中变化事件的 ToggleContainer 组件 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | - | - | 可选 |
handle | 句柄 | 数据 | eventHandle | 绑定句柄 用于后续取消这个具体监听。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。