Cocos24 UI

Cocos Creator 2.4.x 最佳实践

目录结构

cocos/
├── SKILL.md          # 技能说明文档
├── LoadAsset.ts      # [可复用] 资源引用管理器组件
├── LoadSprite.ts     # [可复用] 动态图片加载组件
├── ModelValue.ts     # [可复用] 可监听数值类型
├── UIManager.ts      # [可复用] UI 弹窗管理器
├── UIState.ts        # [可复用] UI 状态管理
├── UIExample.ts      # [示例] UI 控制类
└── UIModelExample.ts # [示例] UI Model 类

说明：

• [可复用] - 最佳实践代码，可直接复制到项目中使用
• [示例] - 参考规范，新建 UI 时按此结构编写

适用场景

用户提供 UI 截图，生成对应的 TypeScript 代码（UI 控制类 + Model 类）。

执行流程：

1. 检查项目中是否存在可复用组件，没有则先复制到项目
2. 分析 UI 截图结构，识别元素类型（Label、Button、Sprite 等）
3. 按照 UI 控制类规范生成代码

可复用组件

生成 UI 代码前，检查以下组件是否存在于项目中，不存在则复制：

UI 开发规范

每个 UI 需要配套一个 Model 类，定义该 UI 所需的所有数据。UI 控制类通过 setData(model) 接收数据。

UI Model 类规范

使用 TypeScript class 定义数据模型，包含 UI 需要展示的所有字段：

/** UI 数据模型示例 */
export class UIModel {
    /** 唯一标识 */
    id: number;
    /** 标题文本 */
    title: string = '';
    /** 是否解锁 */
    isUnlock: boolean = false;
    /** 可监听的数值类型 */
    value: ModelValue;
    /** 最大值 */
    maxValue: number = 100;
    /** 嵌套子模型 */
    items: SubModel[] = [];
}

要点：

• 类名以 Model 结尾
• 属性带类型注解和默认值
• 可嵌套其他 Model 类或数组
• 需要监听变化的数值使用 ModelValue 类型

示例: UIModelExample.ts

UI 控制类规范

创建新的 UI 控制类时，遵循以下结构：

1. 声明引用的组件

使用 @property 装饰器声明所有需要在编辑器中绑定的组件引用：

@property(cc.Label)
label_name: cc.Label = null;

@property(cc.Node)
node_name: cc.Node = null;

@property(I18nLabel)  // 自定义组件
custom_component: CustomComponent = null;

2. setData 方法

统一使用 setData(data) 作为 UI 初始化入口：

data: DataModel = null;

setData(data: DataModel) {
    this.data = data;
    this.initListen();        // 初始化事件监听
    this.updateUI();          // 更新 UI 显示
}

3. click 统一处理点击事件

在节点上绑定 click 事件，通过 currentTarget.name 分发处理：

click(target: cc.Event.EventTouch) {
    switch (target.currentTarget.name) {
        case 'btn_name_1':
            // 处理按钮1点击
            break;
        case 'btn_name_2':
            // 处理按钮2点击
            break;
        default:
            break;
    }
}

4. 事件监听管理

配对使用 initListen() 和 onDestroy() 管理事件订阅，防止内存泄漏：

isListening: boolean = false;

initListen() {
    if (this.isListening) return;
    this.isListening = true;
    this.data.property.on('valueChanged', this.onValueChanged, this);
}

onDestroy() {
    if (!this.isListening) return;
    this.isListening = false;
    this.data.property.off('valueChanged', this.onValueChanged, this);
}

示例: UIExample.ts