# 装饰器使用指南

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

## 什么是装饰器？

装饰器是一种特殊的声明，它能够被附加到类声明、方法、访问符、属性或参数上。在神岛引擎中，我们主要使用 `@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` 装饰器是必需的。
