使用指南
Cocos 组件 / UI / Toggle节点
Cocos 组件 / UI / Toggle 节点手册，包含 6 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。
覆盖范围
- 节点数量：6
- 分类路径：Cocos 组件 / UI / Toggle
典型使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
通用注意事项
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
- 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 获取勾选标记 | toggleGetCheckMark | 1 / 1 | 立即继续 |
| 获取选中状态 | toggleGetIsChecked | 1 / 1 | 立即继续 |
| 静默设置选中状态 | toggleSetIsCheckedWithoutNotify | 3 / 2 | 立即继续 |
| 设置勾选标记 | toggleSetCheckMark | 3 / 2 | 立即继续 |
| 设置选中状态 | toggleSetIsChecked | 3 / 2 | 立即继续 |
| 选中状态变化事件 | toggleToggleBind | 3 / 2 | 立即继续 |
获取勾选标记
获取勾选标记：返回 Toggle 用于显示选中状态的 Sprite 组件。 典型用途：读取当前的勾选标记图片，或判断是否已设置勾选图标。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | toggleGetCheckMark |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | Toggle |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
toggle | 开关 | 数据 | cc.Component / Toggle | 目标开关 要操作的 Toggle 组件 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
checkMark | Sprite | 数据 | cc.Component / Sprite | 勾选标记 Sprite 用于显示选中状态的 Sprite 组件 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取选中状态
获取选中状态：返回 Toggle 当前是否被选中。 典型用途：在角色选择界面获取当前选中的角色，或检测开关是否已打开。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | toggleGetIsChecked |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | Toggle |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
toggle | 开关 | 数据 | cc.Component / Toggle | 目标开关 要操作的 Toggle 组件 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
isChecked | 选中 | 数据 | boolean | 选中状态 true=选中，false=未选中 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
静默设置选中状态
静默设置选中状态：设置 Toggle 的选中状态，但不会触发 toggle 事件和 checkEvents 回调。 适用于需要在代码中修改选中状态但不希望引起事件联动的场景。 典型用途：读取存档后恢复 UI 的勾选状态而不触发事件。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | toggleSetIsCheckedWithoutNotify |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | Toggle |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
toggle | 开关 | 数据 | cc.Component / Toggle | 目标开关 要操作的 Toggle 组件 | - | 必填 |
isChecked | 选中 | 数据 | boolean | 选中状态 true=选中，false=未选中 该操作不会触发 toggle 事件与 checkEvents 回调 | 下拉选择 默认值：false | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
toggle | 开关 | 数据 | cc.Component / Toggle | 目标开关 要操作的 Toggle 组件 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置勾选标记
设置勾选标记：设置 Toggle 用于显示选中状态的 Sprite 组件。 传入 null 可清空勾选标记图片。典型用途：更换勾选图标为自定义图片（如勾号、星号）。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | toggleSetCheckMark |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | Toggle |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
toggle | 开关 | 数据 | cc.Component / Toggle | 目标开关 要操作的 Toggle 组件 | - | 必填 |
checkMark | Sprite | 数据 | cc.Component / Sprite | 勾选标记 Sprite 用于显示选中状态的 Sprite 组件，传入 null 可清空勾选标记图片 | - | 可选 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
toggle | 开关 | 数据 | cc.Component / Toggle | 目标开关 要操作的 Toggle 组件 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置选中状态
设置选中状态：设置 Toggle 的选中状态，会触发 toggle 事件和 checkEvents 回调。 典型用途：在设置界面中打开/关闭音效开关，或实现”全选/取消全选”功能。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | toggleSetIsChecked |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | Toggle |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
toggle | 开关 | 数据 | cc.Component / Toggle | 目标开关 要操作的 Toggle 组件 | - | 必填 |
isChecked | 选中 | 数据 | boolean | 选中状态 true=选中，false=未选中 | 下拉选择 默认值：false | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
toggle | 开关 | 数据 | cc.Component / Toggle | 目标开关 要操作的 Toggle 组件 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
选中状态变化事件
绑定选中状态变化事件：在 Toggle 的选中状态发生变化时触发连接的 执行事件 节点。 每次选中或取消选中时触发。典型用途：角色选择界面中，切换角色时更新详情面板。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | toggleToggleBind |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | Toggle |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | - | - | 可选 |
event | 事件 | 事件 | 事件 | 事件入口 连接到执行事件节点的事件输出引脚 | - | 必填 |
toggle | 开关 | 数据 | cc.Component / Toggle | 目标开关 要监听选中状态变化事件的 Toggle 组件 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | - | - | 可选 |
handle | 句柄 | 数据 | eventHandle | 绑定句柄 用于后续取消这个具体监听。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。