cocos24-ui

Cocos Creator 2.4.x Best Practices

Directory Structure

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

Description：

• [可复用] - Best practice code, can be directly copied into the project for use
• [示例] - Reference specification, write new UIs according to this structure

Applicable Scenarios

The user provides UI screenshots, and the corresponding TypeScript code is generated (UI control class + Model class).

Execution Flow：

1. Check whether reusable components exist in the project; if not, copy them into the project first
2. Analyze the UI screenshot structure and identify element types (Label, Button, Sprite, etc.)
3. Generate code according to the UI control class specification

---

Reusable Components

Before generating UI code, check whether the following components exist in the project; if not, copy them:

File	Description
LoadAsset.ts	Resource reference manager, uniformly manages the reference count of dynamically loaded resources to prevent memory leaks
LoadSprite.ts	Dynamic image loading component, used together with LoadAsset
ModelValue.ts	Observable value type, solves the problems of instant feedback and data consistency under network latency
UIManager.ts	UI popup manager, manages the popup lifecycle in singleton mode
UIState.ts	UI state management, used together with UIManager

---

UI Development Specification

Each UI needs a matching Model class that defines all the data required by that UI. The UI control class receives data through setData(model) .

UI Model Class Specification

Use a TypeScript class to define the data model, including all fields that the UI needs to display:

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

Key Points：

• Class names end with Model ends with
• Properties have type annotations and default values
• Can nest other Model classes or arrays
• Values that need to be monitored for changes use the ModelValue type

Example: UIModelExample.ts

---

UI Control Class Specification

When creating a new UI control class, follow the structure below:

1. Declare referenced components

Use the @property decorator to declare all component references that need to be bound in the editor:

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

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

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

2. setData method

Uniformly use setData(data) as the UI initialization entry point:

data: DataModel = null;

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

3. click uniformly handles click events

Bind the click event on the node, and dispatch and handle it through 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. Event listener management

Use in pairs initListen() and onDestroy() to manage event subscriptions and prevent memory leaks:

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);
}

Example: UIExample.ts