游戏引擎 / 系统课时
让脚本挂到场景节点上
让脚本挂到场景节点上
本课把一个 TypeScript 类变成可挂载的 Cocos Creator 3.8 组件,并把它分别放到两个节点上。最终你会通过两条不同的日志,确认同一份脚本资源能够产生多个独立实例,且各节点的属性不会互相覆盖。
学习目标
- 创建符合 Cocos Creator 3.8 规范的 TypeScript 组件脚本。
- 区分脚本资源、组件类、节点上的组件实例。
- 在属性检查器中挂载和配置组件,并验证运行结果。
脚本资源为什么不等于组件实例
HelloNode.ts 是项目里的脚本资源;@ccclass('HelloNode') 声明可由引擎识别的组件类;只有把它添加到场景节点后,节点上才会拥有相应的组件实例。this.node 始终指向当前实例所属的节点,而不是资源管理器中的脚本文件。

组件实例上的公开属性可以分别保存在场景中,修改 NodeA 的 greeting 不会改变 NodeB。组件是否执行,还取决于所在节点是否激活、组件是否启用,以及场景是否正在运行。
创建并编写 TypeScript 脚本
在资源管理器中选择 assets 下的合适目录,右键选择 TypeScript → NewComponent,将文件命名为 HelloNode。双击打开 HelloNode.ts,把模板替换为以下完整代码并保存:
import { _decorator, Component } from 'cc';
const { ccclass, property } = _decorator;
@ccclass('HelloNode')
export class HelloNode extends Component {
// 每个组件实例都能在属性检查器中独立配置这个值。
@property
public greeting = '你好';
start(): void {
// start 在组件首次进入运行状态时调用一次。
console.log(`[HelloNode] ${this.node.name}: ${this.greeting}`);
}
}预期输出:按下文把脚本挂到两个节点、分别设置属性并预览后,浏览器控制台出现以下两行,先后顺序可能不同:
[HelloNode] NodeA: 你好A
[HelloNode] NodeB: 你好BComponent 提供节点归属和生命周期;@property 把字符串属性暴露到属性检查器;start() 不用手动调用,由引擎在组件首次进入运行状态时调用。项目中 @ccclass 名称需要保持唯一,不要只改文件名却忘记核对类声明。
这里有三个容易混淆的地方:
HelloNode.ts是脚本文件,一般只需要创建一份。HelloNode是组件类,描述组件拥有的属性和行为。- 节点上的
HelloNode是运行时组件实例,不同实例拥有各自的greeting值。
修改脚本代码会影响使用该组件类的实例,但在属性检查器中修改某个节点的 Greeting,不会自动改变其他节点已保存的属性值。
将同一脚本挂到两个节点
- 在已打开的场景中创建两个空节点,依次命名为
NodeA、NodeB。 - 在层级管理器选中
NodeA,把资源管理器中的HelloNode.ts拖进属性检查器;也可以使用 添加组件 → 自定义脚本 → HelloNode。 - 用相同方法为
NodeB添加HelloNode组件。确认两处都出现组件属性Greeting。 - 分别把
Greeting修改为你好A和你好B,保存场景。不要修改代码里的默认值来代替这一步。

完成挂载后,层级管理器仍然只显示 NodeA 和 NodeB 两个节点。脚本组件不是新的子节点,而是附加在节点上的行为模块。选中节点时,才会在属性检查器中看到对应的组件和配置字段。
验证行为并定位挂载问题
在工具栏选择 浏览器预览 和 当前场景,运行后打开浏览器开发者工具的 Console。两条日志分别包含 NodeA、NodeB,就说明两个节点持有独立的组件实例。
再仅取消 NodeB 上该组件的启用勾选,重新预览:此时应只出现 NodeA 的日志。重新启用并预览后,两条日志应恢复。注意,关闭组件与删除组件不同:关闭只会阻止相应的生命周期行为执行,组件配置仍然保留。
如果没有输出,按以下顺序检查:
- 当前预览的是不是已经打开并保存的目标场景。
- TypeScript 文件有没有编译错误,
@ccclass名称有没有冲突。 HelloNode是否真正出现在目标节点的属性检查器里。- 节点的 Active 和组件的 Enabled 是否开启。
- 浏览器 Console 是否过滤了普通日志。
如果日志中的节点名正确,但 greeting 仍是默认值 你好,说明组件运行正常,问题更可能出在属性检查器的赋值或场景保存上。重新检查对应节点的 Greeting,保存场景后再刷新预览即可。
这次验收的关键不是看到脚本文件存在,而是让两个节点分别执行自己的组件逻辑,并能在编辑器中独立配置属性。