Cocos 装饰器

在 Cocos Creator 中，装饰器（Decorator）是 TypeScript 中的一项强大功能，广泛应用于 Cocos 的组件系统、场景系统等。装饰器通常用于为类、方法、属性、参数等添加元数据，或者对类和方法进行额外的功能扩展。

Cocos Creator 支持使用 TypeScript 装饰器，并通过这些装饰器来简化代码和增强可读性。常见的装饰器包括 @ccclass、@property、@executeInEditMode 等，帮助你在 Cocos Creator 中快速定义组件和其属性，同时提高代码的可维护性和扩展性。

Cocos Creator 中常用的装饰器

1. @ccclass

@ccclass 装饰器用于标记一个类为 Cocos Creator 的组件类，使其可以挂载到场景中的节点上。

typescriptCopy Code

@ccclass
export default class MyComponent extends Component {
    // 在这里定义类的逻辑
}

• @ccclass 是 Cocos Creator 中最常用的装饰器，它让一个普通的 TypeScript 类变成一个组件类。
• 使用 @ccclass 后，Cocos Creator 会自动注册这个类，并允许你在编辑器中通过拖拽将其挂载到节点上。

2. @property

@property 装饰器用于声明组件类中的属性，这些属性会暴露给 Cocos Creator 编辑器，允许你在编辑器中对它们进行设置。

typescriptCopy Code

@ccclass
export default class MyComponent extends Component {

    @property
    public speed: number = 10;

    @property(cc.SpriteFrame)
    public sprite: SpriteFrame = null;
}

• 通过 @property 装饰器声明的变量，可以在 Cocos Creator 编辑器的属性面板中显示，并且支持类型提示。
• @property 可以加上不同的参数来指定属性的类型、范围、默认值等。例如：
  • @property(cc.Node) 表示该属性是一个 Node 类型。
  • @property(cc.Integer) 用于声明整数类型。
  • @property({ type: cc.Float, min: 0, max: 100 }) 用于指定属性的类型，并限制它的范围。

3. @executeInEditMode

@executeInEditMode 装饰器用于标记一个组件，使其在编辑模式下（即不运行游戏时）也能执行。

typescriptCopy Code

@ccclass
@executeInEditMode
export default class MyComponent extends Component {
    // 组件逻辑
}

• 通常情况下，Cocos Creator 中的组件只在游戏运行时才会执行。加上 @executeInEditMode 后，组件即使在编辑模式下也会执行它的生命周期函数，如 start()、update() 等。
• 这对于需要在编辑模式下进行自定义编辑或更新的功能非常有用。

4. @requireComponent

@requireComponent 装饰器用于标记一个组件类，要求该组件的挂载节点上必须有其他特定的组件。这在编写组件时非常有用，确保在使用某个组件时，依赖的组件被正确地添加到节点上。

typescriptCopy Code

@ccclass
@requireComponent(cc.RigidBody)
export default class MyComponent extends Component {
    // 在这里定义类的逻辑
}

• 通过 @requireComponent 装饰器，Cocos Creator 会自动在组件挂载的节点上检查是否存在 cc.RigidBody 组件，如果没有，则会自动添加该组件。
• 这种方式确保了组件的依赖关系，并避免了运行时出现找不到依赖组件的错误。

5. @menu

@menu 装饰器用于设置组件类在 Cocos Creator 编辑器的菜单中显示的名称和路径。这样可以帮助我们将组件更好地组织和分类。

typescriptCopy Code

@ccclass
@menu("Custom/MyComponent")
export default class MyComponent extends Component {
    // 组件逻辑
}

• 通过 @menu("Custom/MyComponent")，组件在 Cocos Creator 编辑器中的组件面板中会显示为 Custom 目录下的 MyComponent，有助于组织和分类组件。

6. @disallowMultiple

@disallowMultiple 装饰器用于指定一个组件在同一节点上不能出现多个实例。如果尝试将相同类型的组件附加到同一节点上，Cocos Creator 将会提示错误。

typescriptCopy Code

@ccclass
@disallowMultiple
export default class MyComponent extends Component {
    // 组件逻辑
}

• 这个装饰器可以防止某个组件被多次挂载到同一个节点上，从而避免不必要的冲突。

7. @range

@range 装饰器用于为数值类型的属性添加范围限制。这通常用于控制数值属性在 Cocos Creator 编辑器中的输入范围。

typescriptCopy Code

@ccclass
export default class MyComponent extends Component {
    @property
    @range(0, 100)
    public health: number = 50;
}

• @range(0, 100) 表示该属性的值范围为 0 到 100，这可以帮助开发者在编辑器中更直观地设置属性值。

8. @tooltip

@tooltip 装饰器用于为属性添加工具提示，帮助开发者在 Cocos Creator 编辑器中理解属性的含义。

typescriptCopy Code

@ccclass
export default class MyComponent extends Component {

    @property
    @tooltip("Player's health value")
    public health: number = 100;
}

• @tooltip("Player's health value") 将在编辑器属性面板中显示一个提示文本，解释该属性的作用。

其他装饰器的应用

Cocos Creator 中的装饰器并不限于上面列举的几个，还有很多其他功能强大的装饰器。以下是一些常见的装饰器和它们的作用：

• @button：标记某个函数为按钮点击事件处理函数。
• @executeInEditMode：使组件即使在编辑模式下也能够执行生命周期方法。

总结

Cocos Creator 中的装饰器是通过 TypeScript 提供的元编程能力，简化了开发过程，并且使得组件和属性的声明更加清晰和直观。装饰器不仅帮助开发者更高效地进行组件化开发，而且通过其特性使得编辑器与游戏逻辑更加紧密地结合，极大提高了开发效率。

通过使用这些装饰器，Cocos Creator 的组件系统变得更加灵活和功能强大，开发者可以通过简单的注解快速完成复杂的组件功能，并提高了代码的可读性和可维护性。