ArenaPro Creator

Appearance

装饰器使用指南 ​

装饰器是神岛引擎组件系统中的重要特性，它能帮助我们更好地管理和使用组件。本指南将帮助你理解和正确使用装饰器。

什么是装饰器？ ​

装饰器是一种特殊的声明，它能够被附加到类声明、方法、访问符、属性或参数上。在神岛引擎中，我们主要使用 @apclass 装饰器来标记和注册组件类。

@apclass 装饰器 ​

基本用法 ​

typescript
import { _decorator, Component } from "@dao3fun/component";
const { apclass } = _decorator;

@apclass("PlayerController")
export class PlayerController extends Component<GameEntity> {
  // 组件实现...
}

为什么需要使用装饰器？ ​

@apclass 装饰器的主要作用是：

  • 注册组件到全局组件表
  • 支持通过字符串名称创建组件实例

使用示例 ​

✅ 正确的使用方式 ​

typescript
@apclass("MovementComponent")
export class MovementComponent extends Component<GameEntity> {
  speed = 5;

  update(dt: number) {
    this.node.entity.position.x += this.speed * dt;
  }
}

// 可以通过字符串名称添加组件
const node = new EntityNode();
node.addComponent("MovementComponent");

❌ 错误的使用方式 ​

typescript
export class MovementComponent extends Component<GameEntity> {
  speed = 5;
}

const node = new EntityNode();
node.addComponent("MovementComponent"); // 错误：找不到组件

最佳实践 ​

  1. 命名规范

    typescript
    @apclass("PlayerController") // 装饰器名称与类名保持一致
export class PlayerController extends Component<GameEntity> {}

  2. 导入方式

    typescript
    // 推荐的导入方式
import { _decorator, Component } from "@dao3fun/component";
const { apclass } = _decorator;

  3. 类型参数

    typescript
    // 指定正确的实体类型
@apclass("EnemyAI")
export class EnemyAI extends Component<GameEntity> {}

注意事项 ​

  1. 装饰器名称必须是唯一的
  2. 装饰器名称建议与类名保持一致
  3. 未使用装饰器的组件类无法通过字符串名称添加
  4. 确保在 tsconfig.json 中启用了装饰器支持：
    json
    {
  "compilerOptions": {
    "experimentalDecorators": true
  }
}

常见问题 ​

Q: 为什么我的组件无法通过字符串名称添加？ ​

A: 检查是否正确使用了 @apclass 装饰器，以及装饰器名称是否正确。

Q: 装饰器名称可以与类名不同吗？ ​

A: 技术上可以，但建议保持一致以避免混淆。

Q: 一个组件类可以使用多个装饰器吗？ ​

A: 可以，但 @apclass 装饰器是必需的。