使用指南
Cocos 组件 / UI / UICoordinateTracker节点
Cocos 组件 / UI / UICoordinateTracker 节点手册，包含 11 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。
覆盖范围
- 节点数量：11
- 分类路径：Cocos 组件 / UI / UICoordinateTracker
典型使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
通用注意事项
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
- 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 获取 3D 相机 | uiCoordinateTrackerGetCamera | 1 / 1 | 立即继续 |
| 获取基准距离 | uiCoordinateTrackerGetDistance | 1 / 1 | 立即继续 |
| 获取距离缩放 | uiCoordinateTrackerGetUseScale | 1 / 1 | 立即继续 |
| 获取目标 UI 节点 | uiCoordinateTrackerGetTarget | 1 / 1 | 立即继续 |
| 获取所有属性 | uiCoordinateTrackerGetProperties | 1 / 4 | 立即继续 |
| 设置 3D 相机 | uiCoordinateTrackerSetCamera | 3 / 2 | 立即继续 |
| 设置基准距离 | uiCoordinateTrackerSetDistance | 3 / 2 | 立即继续 |
| 设置距离缩放 | uiCoordinateTrackerSetUseScale | 3 / 2 | 立即继续 |
| 设置目标 UI 节点 | uiCoordinateTrackerSetTarget | 3 / 2 | 立即继续 |
| 设置所有属性 | uiCoordinateTrackerSetProperties | 6 / 2 | 立即继续 |
| 坐标同步事件 | uiCoordinateTrackerSyncBind | 3 / 2 | 立即继续 |
获取 3D 相机
获取 3D 相机：返回用于坐标转换的 3D 相机组件。 该相机用于将挂载 UICoordinateTracker 的 3D 节点世界坐标转换为 UI 节点本地坐标。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | uiCoordinateTrackerGetCamera |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | UICoordinateTracker |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 注意： 挂载此组件的节点本身就是被跟踪的 3D 节点 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
camera | 相机 | 数据 | cc.Component / Camera | 3D 相机 用于坐标转换的 Camera 组件 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取基准距离
获取基准距离：返回距相机多远时 UI 显示正常大小的基准距离值。 useScale 与 distance 共同决定透视远近感：当 3D 节点距相机的距离等于此值时，UI 按原始大小显示；更远则缩小，更近则放大。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | uiCoordinateTrackerGetDistance |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | UICoordinateTracker |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 注意： 挂载此组件的节点本身就是被跟踪的 3D 节点 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
distance | 距离 | 数据 | number | 基准距离 距相机多远时 UI 显示正常大小 与 useScale 配合模拟 3D 透视远近感 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取距离缩放
获取距离缩放开关：返回是否根据 3D 节点与相机的距离对映射后的 UI 进行透视缩放。 useScale 与 distance 共同决定透视远近感：启用时，距相机越远 UI 越小，越近越大，模拟 3D 透视效果。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | uiCoordinateTrackerGetUseScale |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | UICoordinateTracker |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 注意： 挂载此组件的节点本身就是被跟踪的 3D 节点 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
useScale | 启用 | 数据 | boolean | 距离缩放开关 true=启用透视缩放，false=禁用 与 distance 配合模拟 3D 透视远近感 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取目标 UI 节点
获取目标 UI 节点：返回 UICoordinateTracker 映射后的 UI 参考节点。 注意： 重要：挂载此组件的节点本身才是被跟踪的 3D 节点，target 是映射后的 UI 参考节点/坐标系（用于确定映射后坐标在哪个 UI 节点的本地坐标系下）。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | uiCoordinateTrackerGetTarget |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | UICoordinateTracker |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 注意： 挂载此组件的节点本身就是被跟踪的 3D 节点 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
target | UI 节点 | 数据 | cc.Node | 目标 UI 节点 映射后的 UI 参考节点，映射坐标将相对于此节点的本地坐标系 注意： 这不是被跟踪的 3D 目标，被跟踪的是挂载组件的节点本身 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取所有属性
一次性读出坐标跟踪器的全部常用属性：目标 UI 节点、相机、距离缩放开关、基准距离。等同于连接多个 获取类节点，但只用一个节点即可。适合调试、序列化、批量比较等场景。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | uiCoordinateTrackerGetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | UICoordinateTracker |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 注意： 挂载此组件的节点本身就是被跟踪的 3D 节点 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
target | UI 节点 | 数据 | cc.Node | 目标 UI 节点 映射后的 UI 参考节点 | - | 可选 |
camera | 相机 | 数据 | cc.Component / Camera | 3D 相机 用于坐标转换的 Camera 组件 | - | 可选 |
useScale | 启用 | 数据 | boolean | 距离缩放开关 是否启用透视缩放 | - | 可选 |
distance | 距离 | 数据 | number | 基准距离 距相机多远时 UI 显示正常大小 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置 3D 相机
设置 3D 相机：设置用于坐标转换的 3D 相机组件。 该相机用于将挂载 UICoordinateTracker 的 3D 节点世界坐标转换为 UI 节点本地坐标。 传入 null 可清空相机，此时坐标同步将暂停。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | uiCoordinateTrackerSetCamera |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | UICoordinateTracker |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 注意： 挂载此组件的节点本身就是被跟踪的 3D 节点 | - | 必填 |
camera | 相机 | 数据 | cc.Component / Camera | 3D 相机 用于坐标转换的 Camera 组件，传入 null 可暂停坐标同步 | - | 可选 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置基准距离
设置基准距离：设置距相机多远时 UI 显示正常大小的基准距离值。 useScale 与 distance 共同决定透视远近感：当 3D 节点距相机的距离等于此值时，UI 按原始大小显示；更远则缩小，更近则放大。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | uiCoordinateTrackerSetDistance |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | UICoordinateTracker |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 注意： 挂载此组件的节点本身就是被跟踪的 3D 节点 | - | 必填 |
distance | 距离 | 数据 | number | 基准距离 距相机多远时 UI 显示正常大小 与 useScale 配合模拟 3D 透视远近感 | 输入框 默认值：1 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置距离缩放
设置距离缩放开关：设置是否根据 3D 节点与相机的距离对映射后的 UI 进行透视缩放。 useScale 与 distance 共同决定透视远近感：启用时，距相机越远 UI 越小，越近越大，模拟 3D 透视效果。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | uiCoordinateTrackerSetUseScale |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | UICoordinateTracker |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 注意： 挂载此组件的节点本身就是被跟踪的 3D 节点 | - | 必填 |
useScale | 启用 | 数据 | boolean | 距离缩放开关 true=启用透视缩放，false=禁用 与 distance 配合模拟 3D 透视远近感 | 下拉选择 默认值：true | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置目标 UI 节点
设置目标 UI 节点：设置 UICoordinateTracker 映射后的 UI 参考节点。 注意： 重要：挂载此组件的节点本身才是被跟踪的 3D 节点，target 是映射后的 UI 参考节点/坐标系（用于确定映射后坐标在哪个 UI 节点的本地坐标系下）。 传入 null 可清空目标节点，此时坐标同步将暂停。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | uiCoordinateTrackerSetTarget |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | UICoordinateTracker |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 注意： 挂载此组件的节点本身就是被跟踪的 3D 节点 | - | 必填 |
target | UI 节点 | 数据 | cc.Node | 目标 UI 节点 映射后的 UI 参考节点，传入 null 可暂停坐标同步 注意： 这不是被跟踪的 3D 目标，被跟踪的是挂载组件的节点本身 | - | 可选 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置所有属性
一次性批量修改坐标跟踪器的多个常用属性。 公开引脚语义（重要）：除 exe 与 uiCoordinateTracker 外，所有可写属性引脚默认不公开（isPublic: false），只有被显式公开的引脚才参与写入。若想保留目标属性原值不变，必须保持引脚不公开——仅断开连线不够，已公开的引脚会用内联控件默认值覆盖原值。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | uiCoordinateTrackerSetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | UICoordinateTracker |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 注意： 挂载此组件的节点本身就是被跟踪的 3D 节点 | - | 必填 |
target | UI 节点 | 数据 | cc.Node | 目标 UI 节点 映射后的 UI 参考节点。默认不公开；公开后才参与写入。 | - | 可选 默认隐藏 |
camera | 相机 | 数据 | cc.Component / Camera | 3D 相机 用于坐标转换的 Camera 组件。默认不公开；公开后才参与写入。 | - | 可选 默认隐藏 |
useScale | 启用 | 数据 | boolean | 距离缩放开关 是否启用透视缩放。默认不公开；公开后才参与写入。 | 下拉选择 默认值：true | 可选 默认隐藏 |
distance | 距离 | 数据 | number | 基准距离 距相机多远时 UI 显示正常大小。默认不公开；公开后才参与写入。 | 输入框 默认值：1 | 可选 默认隐藏 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要操作的 UICoordinateTracker 组件 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
坐标同步事件
绑定坐标同步完成事件：在 UICoordinateTracker 每帧坐标同步完成后触发连接的 执行事件 节点。 事件数据包含两个字段：
- localUIPos：映射后的 UI 本地坐标，相对于目标 UI 节点的本地坐标系
- distanceScale：距离缩放比（Number），可用于缩放 UI 元素以模拟 3D 透视远近感 注意： 只有当目标 UI 节点和相机都已设置且有效时，同步才会触发。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | uiCoordinateTrackerSyncBind |
| 分类 | Cocos 组件 |
| 二级分类 | UI |
| 分组 | UICoordinateTracker |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | - | - | 可选 |
event | 事件 | 事件 | 事件 | 事件入口 连接到执行事件节点的事件输出引脚 | - | 必填 |
uiCoordinateTracker | 跟踪器 | 数据 | cc.Component / UICoordinateTracker | 坐标跟踪器 要监听同步完成事件的 UICoordinateTracker 组件 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | - | - | 可选 |
handle | 句柄 | 数据 | eventHandle | 绑定句柄 用于后续取消这个具体监听。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。