使用指南
Cocos 组件 / UI / SafeArea节点
Cocos 组件 / UI / SafeArea 节点手册，包含 3 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。
覆盖范围
- 节点数量：3
- 分类路径：Cocos 组件 / UI / SafeArea
典型使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
通用注意事项
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
- 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 更新安全区域 | safeAreaUpdateArea | 2 / 2 | 立即继续 |
| 获取对称适配 | safeAreaGetSymmetric | 1 / 1 | 立即继续 |
| 设置对称适配 | safeAreaSetSymmetric | 3 / 2 | 立即继续 |
更新安全区域
手动更新安全区域：立即根据当前设备的屏幕安全区域重新调整 UI 位置，避免被刘海屏、挖孔屏或圆角遮挡。 适用场景：屏幕旋转后、窗口尺寸变化、折叠屏展开/折叠、动态切换 UI 布局等。正常情况下 SafeArea 启用时会自动适配一次，此节点用于需要主动刷新的情况。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | safeAreaUpdateArea |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | SafeArea |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
safeArea | 安全区域 | 数据 | cc.Component / SafeArea | 目标安全区域 要操作的 SafeArea 组件 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
safeArea | 安全区域 | 数据 | cc.Component / SafeArea | 安全区域 原样传出，方便链式连接 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取对称适配
获取对称适配状态：返回是否启用对称安全区域适配。 值为 true 时，左右/上下方向各取较小值统一适配，在异形屏（刘海屏、挖孔屏）四周保持均匀间距。 值为 false 时，各边独立计算适配值。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | safeAreaGetSymmetric |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | SafeArea |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
safeArea | 安全区域 | 数据 | cc.Component / SafeArea | 目标安全区域 要操作的 SafeArea 组件 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
symmetric | 对称适配 | 数据 | boolean | true=对称适配（各方向均匀留边），false=各边独立适配 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置对称适配
设置对称适配：控制是否启用对称安全区域适配。 设为 true 时 UI 在异形屏四周均匀留边，避免内容被刘海或挖孔区域遮挡。 修改后可手动连接 更新安全区域 节点立即生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | safeAreaSetSymmetric |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | SafeArea |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
safeArea | 安全区域 | 数据 | cc.Component / SafeArea | 目标安全区域 要操作的 SafeArea 组件 | - | 必填 |
symmetric | 对称适配 | 数据 | boolean | 对称适配- true：左右/上下对称适配 - false：各边独立适配 | 开关 默认值：true | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
safeArea | 安全区域 | 数据 | cc.Component / SafeArea | 安全区域 原样传出，方便链式连接 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。