使用指南
Cocos 组件 / 后效 / DOF节点
Cocos 组件 / 后效 / DOF 节点手册，包含 8 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。
覆盖范围
- 节点数量：8
- 分类路径：Cocos 组件 / 后效 / DOF
典型使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
通用注意事项
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
- 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 获取焦点距离 | dofGetFocusDistance | 1 / 1 | 立即继续 |
| 获取清晰范围 | dofGetFocusRange | 1 / 1 | 立即继续 |
| 获取全部属性 | dofGetProperties | 1 / 3 | 立即继续 |
| 获取散景半径 | dofGetBokehRadius | 1 / 1 | 立即继续 |
| 设置焦点距离 | dofSetFocusDistance | 3 / 2 | 立即继续 |
| 设置清晰范围 | dofSetFocusRange | 3 / 2 | 立即继续 |
| 设置全部属性 | dofSetProperties | 5 / 2 | 立即继续 |
| 设置散景半径 | dofSetBokehRadius | 3 / 2 | 立即继续 |
获取焦点距离
获取焦点距离：读取当前景深效果中清晰焦点的深度位置。 深度值接近该位置的区域呈现清晰，远离该位置的区域逐渐虚化。默认值为 0。增大值会把清晰区域推向更远处，减小则更靠近镜头。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | dofGetFocusDistance |
| 分类 | Cocos 组件 |
| 二级分类 | 后效 |
| 分组 | DOF |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
dof | DOF | 数据 | cc.Component / DOF | 目标 DOF 组件 要操作的景深后效组件。 DOF（景深）用于模拟镜头对焦效果，让画面中特定距离的物体清晰、其他距离的物体模糊，营造真实感。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
focusDistance | 焦点距离 | 数据 | number | 焦点距离 清晰焦点所在的深度位置，非负。深度接近该值的区域更清晰；默认值 0。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取清晰范围
获取清晰范围：读取焦点附近保持清晰的深度范围宽度。 值越小景深越浅，清晰区域越窄；值越大更多区域保持清晰，过渡更平滑。默认值为 0（表示极窄的清晰带，通常建议设为大于 0 的值以获得更稳定的过渡效果）。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | dofGetFocusRange |
| 分类 | Cocos 组件 |
| 二级分类 | 后效 |
| 分组 | DOF |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
dof | DOF | 数据 | cc.Component / DOF | 目标 DOF 组件 要操作的景深后效组件。 DOF（景深）用于模拟镜头对焦效果，让画面中特定距离的物体清晰、其他距离的物体模糊，营造真实感。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
focusRange | 清晰范围 | 数据 | number | 清晰范围 焦点附近保持清晰的深度范围，非负。越小景深越浅；默认值 0（语义为极窄清晰带，通常建议大于 0）。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取全部属性
一次性读取 DOF 全部属性：聚合读取焦点距离（focusDistance）、清晰范围（focusRange）和散景半径（bokehRadius）。适合需要同时读取多个属性时减少节点数量。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | dofGetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 后效 |
| 分组 | DOF |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
dof | DOF | 数据 | cc.Component / DOF | 目标 DOF 组件 要操作的景深后效组件。 DOF（景深）用于模拟镜头对焦效果，让画面中特定距离的物体清晰、其他距离的物体模糊，营造真实感。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
focusDistance | 焦点距离 | 数据 | number | 焦点距离，非负，默认 0 | - | 可选 |
focusRange | 清晰范围 | 数据 | number | 清晰范围，非负，默认 0（通常建议大于 0） | - | 可选 |
bokehRadius | 散景半径 | 数据 | number | 散景半径，范围 1 ~ 10，默认 1 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取散景半径
获取散景半径：读取失焦区域的虚化扩散程度。 值越大，失焦区域的虚化越明显，但过大可能带来画面模糊过重和性能开销。取值范围 1 ~ 10，默认值 1。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | dofGetBokehRadius |
| 分类 | Cocos 组件 |
| 二级分类 | 后效 |
| 分组 | DOF |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
dof | DOF | 数据 | cc.Component / DOF | 目标 DOF 组件 要操作的景深后效组件。 DOF（景深）用于模拟镜头对焦效果，让画面中特定距离的物体清晰、其他距离的物体模糊，营造真实感。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
bokehRadius | 散景半径 | 数据 | number | 散景半径 范围 1 ~ 10，默认值 1。越大虚化越明显，但过大会带来模糊过重和性能压力。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置焦点距离
设置焦点距离：控制景深效果中清晰焦点的深度位置。 增大值会把清晰区域推向更远处，减小则更靠近镜头。默认值为 0（非负约束）。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | dofSetFocusDistance |
| 分类 | Cocos 组件 |
| 二级分类 | 后效 |
| 分组 | DOF |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
dof | DOF | 数据 | cc.Component / DOF | 目标 DOF 组件 要操作的景深后效组件。 DOF（景深）用于模拟镜头对焦效果，让画面中特定距离的物体清晰、其他距离的物体模糊，营造真实感。 | - | 必填 |
focusDistance | 焦点距离 | 数据 | number | 焦点距离 清晰焦点所在的深度位置，非负，默认值 0。 | 输入框 默认值：0 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
dof | DOF | 数据 | cc.Component / DOF | 目标 DOF 组件 透传当前操作的 DOF 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置清晰范围
设置清晰范围：控制焦点附近保持清晰的深度范围宽度。 值越小景深越浅，清晰区域越窄；值越大更多区域保持清晰，过渡更平滑。默认值为 0，通常建议设为大于 0 的值以获得更稳定的过渡效果。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | dofSetFocusRange |
| 分类 | Cocos 组件 |
| 二级分类 | 后效 |
| 分组 | DOF |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
dof | DOF | 数据 | cc.Component / DOF | 目标 DOF 组件 要操作的景深后效组件。 DOF（景深）用于模拟镜头对焦效果，让画面中特定距离的物体清晰、其他距离的物体模糊，营造真实感。 | - | 必填 |
focusRange | 清晰范围 | 数据 | number | 清晰范围 非负，默认值 0（语义为极窄清晰带，通常建议大于 0 以获得稳定过渡）。 | 输入框 默认值：0 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
dof | DOF | 数据 | cc.Component / DOF | 目标 DOF 组件 透传当前操作的 DOF 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置全部属性
批量修改 DOF 全部属性：聚合写入焦点距离（focusDistance）、清晰范围（focusRange）和散景半径（bokehRadius）。 说明：除执行流与 DOF 组件引脚外，所有可写属性引脚默认不公开，只有被显式公开的属性才参与写入。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | dofSetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 后效 |
| 分组 | DOF |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
dof | DOF | 数据 | cc.Component / DOF | 目标 DOF 组件 要操作的景深后效组件。 DOF（景深）用于模拟镜头对焦效果，让画面中特定距离的物体清晰、其他距离的物体模糊，营造真实感。 | - | 必填 |
focusDistance | 焦点距离 | 数据 | number | 焦点距离，非负，默认 0 | 输入框 默认值：0 | 可选 默认隐藏 |
focusRange | 清晰范围 | 数据 | number | 清晰范围，非负，默认 0（通常建议大于 0） | 输入框 默认值：0 | 可选 默认隐藏 |
bokehRadius | 散景半径 | 数据 | number | 散景半径，范围 1 ~ 10，默认 1 | 输入框 默认值：1 | 可选 默认隐藏 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
dof | DOF | 数据 | cc.Component / DOF | 目标 DOF 组件 透传当前操作的 DOF 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置散景半径
设置散景半径：控制失焦区域的虚化扩散程度。 值越大虚化越明显，但过大可能带来画面模糊过重和性能开销。建议在满足视觉效果的前提下使用较小的值。取值范围 1 ~ 10，默认值 1。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | dofSetBokehRadius |
| 分类 | Cocos 组件 |
| 二级分类 | 后效 |
| 分组 | DOF |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
dof | DOF | 数据 | cc.Component / DOF | 目标 DOF 组件 要操作的景深后效组件。 DOF（景深）用于模拟镜头对焦效果，让画面中特定距离的物体清晰、其他距离的物体模糊，营造真实感。 | - | 必填 |
bokehRadius | 散景半径 | 数据 | number | 散景半径 范围 1 ~ 10，默认值 1。越大虚化越明显，但过大会带来模糊过重和性能压力。 | 输入框 默认值：1 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
dof | DOF | 数据 | cc.Component / DOF | 目标 DOF 组件 透传当前操作的 DOF 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。