游戏引擎 / 系统课时
创建第一个 TypeScript 组件
创建第一个 TypeScript 组件
把脚本文件放进项目并不等于让脚本开始工作。本节创建一个能挂载到节点、能在预览中输出状态的组件,逐步核对文件导入、类注册、Inspector 属性与生命周期之间的关系,建立后续脚本的最小验证入口。
学习目标
- 创建并挂载 TypeScript 组件,确认脚本被场景实际使用。
- 区分类型标注、组件注册和可编辑属性各自的作用。
- 用一次明确的预览输出检查组件是否执行。
从脚本资产到组件实例
准备一个已有场景的 Cocos Creator 3.8 项目。组件是附着在节点上的行为实例,同一份脚本可以被多个节点使用;每个实例拥有自己的属性值。只把文件保存在 assets 下,没有把组件加入场景,预览时不会自动执行它的 start。
在 Assets 面板选中 scripts 文件夹,右键选择 TypeScript 的组件脚本模板,命名为 HelloScore。双击文件进入代码编辑器,用下面代码替换模板。不同补丁版本的菜单显示可能略有差异,关键是创建继承 Component 的 TypeScript 脚本,再等待编辑器完成导入。
写出可观察的组件
文件:HelloScore.ts。这是片段示例,文件内容完整,但运行上下文必须是 Creator 3.8 项目与场景节点,不能作为普通 Node.js 程序执行。
import { _decorator, Component } from 'cc';
const { ccclass, property } = _decorator;
@ccclass('HelloScore')
export class HelloScore extends Component {
// 编辑器值会随场景保存,代码默认值用于新实例。
@property
initialScore = 10;
start(): void {
// 一次性验证放在 start,避免每帧刷屏。
console.log(`score:${this.initialScore}`);
}
}预期结果:挂载后把 initialScore 设为 25,保存场景并开始预览,控制台出现一条对应输出。
score:25import 从引擎模块 cc 取得运行时类;extends Component 使脚本进入组件机制。@ccclass 注册引擎识别的类名,同一项目中不要重复这个注册名。TypeScript 的 number 类型与引擎注册是不同层面的信息,不会仅凭类型标注就让一个普通类成为组件。
@property 给属性增加编辑器和序列化信息。initialScore 的数值初始值可以用于识别属性类型;以后加入 Node、Label 等对象引用时,还需要写明引擎可识别的属性类型。默认值、Inspector 保存值和预览中的运行时修改也应区分:本例应以场景保存的 25 开始。
挂载并检查实际执行
- 在 Hierarchy 创建一个活动节点,命名为 ScoreProbe。
- 选中该节点,把 HelloScore 脚本拖入 Inspector,确认出现组件卡片。
- 将 initialScore 改为 25,保存场景,预览当前场景。
- 查看预览控制台,确认输出次数和值;停止后改为 30 再次预览。
第二次应输出 score:30。这个验证同时证明脚本已经成功导入、场景引用了组件、属性序列化值进入实例。节点和组件都应处于启用状态;多挂一份组件就可能多一条输出,不能把多次日志直接认定为 start 重复调用。
没有日志时沿挂载链排查
先看编辑器是否报语法或导入错误,再确认预览的是保存过的目标场景,最后检查节点是否活动、组件是否启用。若组件卡片显示脚本丢失,应修复脚本资产引用;若提示注册名冲突,应搜索重复的 ccclass 名称。不要靠每帧输出弥补挂载问题。
Creator 的脚本构建与独立 TypeScript 类型检查不是同一个验证步骤。编辑器能预览,不代表全部类型约束都已通过;本节先建立真实组件入口,后续纯逻辑例程再独立执行严格类型检查。
3.8 文档标明支持 TypeScript 4.1;本课程的独立验收工具使用 5.9,示例避免依赖新语法。Creator 构建不读取 tsconfig 做类型检查,类型报错也不会自动阻止构建,因此应保留 IDE 或独立检查。不要把验收工具版本误写成引擎内置版本。依据 语言支持、脚本创建 和 装饰器说明。