GFramework/docs/zh-CN/source-generators/enum-generator.md

# 枚举扩展生成器

> 自动为枚举类型生成扩展方法

## 概述

枚举扩展生成器为标记了 `[GenerateEnumExtensions]` 属性的枚举自动生成两种扩展方法：

1. **IsX 方法**：为每个枚举值生成判断方法
2. **IsIn 方法**：判断枚举值是否在指定集合中

## 基础使用

```csharp
using GFramework.SourceGenerators.Abstractions.Enums;

[GenerateEnumExtensions]
public enum GameState
{
    Normal,
    Paused,
    GameOver
}
```

## 生成的代码

编译器会自动生成如下扩展方法：

```csharp
// <auto-generated/>
public static class GameStateExtensions
{
    // 为每个枚举值生成 IsX 方法
    public static bool IsNormal(this GameState value)
        => value == GameState.Normal;

    public static bool IsPaused(this GameState value)
        => value == GameState.Paused;

    public static bool IsGameOver(this GameState value)
        => value == GameState.GameOver;

    // 生成 IsIn 方法
    public static bool IsIn(this GameState value, params GameState[] values)
    {
        if (values == null) return false;
        foreach (var v in values) if (value == v) return true;
        return false;
    }
}
```

## 使用示例

```csharp
var state = GameState.Paused;

// 使用 IsX 方法
if (state.IsPaused())
{
    Console.WriteLine("游戏已暂停");
}

// 使用 IsIn 方法
if (state.IsIn(GameState.Paused, GameState.GameOver))
{
    Console.WriteLine("游戏未在运行中");
}
```

## 配置选项

可以通过属性参数控制生成行为：

```csharp
[GenerateEnumExtensions(
    GenerateIsMethods = true,      // 是否生成 IsX 方法（默认 true）
    GenerateIsInMethod = true      // 是否生成 IsIn 方法（默认 true）
)]
public enum GameState
{
    Normal,
    Paused,
    GameOver
}
```

### 配置选项说明

#### 实际支持的选项

当前版本只支持以下配置选项：

| 参数                 | 类型   | 默认值  | 说明                |
|--------------------|------|------|-------------------|
| GenerateIsMethods  | bool | true | 是否为每个枚举值生成 IsX 方法 |
| GenerateIsInMethod | bool | true | 是否生成 IsIn 方法      |

#### 未实现的选项

以下选项在属性定义中存在，但生成器当前版本**未实现**：

- `GenerateHasMethod`：未实现 HasX 方法生成
- `IncludeToString`：未实现 ToString 扩展方法

```csharp
// ❌ 以下选项不会生效
[GenerateEnumExtensions(
    GenerateIsMethods = true,
    GenerateIsInMethod = true,
    GenerateHasMethod = true,      // 未实现，参数会被忽略
    IncludeToString = true          // 未实现,参数会被忽略
)]
public enum GameState
{
    Normal,
    Paused,
    GameOver
}
```

**注意**：这些选项计划在后续版本中实现，届时会更新文档说明。

### 只生成 IsX 方法

```csharp
[GenerateEnumExtensions(GenerateIsInMethod = false)]
public enum GameState
{
    Normal,
    Paused
}

// 只生成 IsNormal() 和 IsPaused()，不生成 IsIn()
```

### 只生成 IsIn 方法

```csharp
[GenerateEnumExtensions(GenerateIsMethods = false)]
public enum GameState
{
    Normal,
    Paused
}

// 只生成 IsIn()，不生成 IsNormal() 和 IsPaused()
```

## 最佳实践

### 1. 命名约定

生成的方法名基于枚举值名称：

- `Normal` → `IsNormal()`
- `GameOver` → `IsGameOver()`
- `HTTP_ERROR` → `IsHTTP_ERROR()`

### 2. 性能考虑

生成的方法是内联的，性能与手写代码相同：
```csharp
// 生成的代码
public static bool IsNormal(this GameState value)
    => value == GameState.Normal;

// 等价于手写
if (state == GameState.Normal) { }
```

### 3. 可读性提升

```csharp
// 使用生成的方法（推荐）
if (state.IsPaused())
{
    ResumeGame();
}

// 直接比较（不推荐）
if (state == GameState.Paused)
{
    ResumeGame();
}
```

## 实际应用示例

### 游戏状态管理

```csharp
[GenerateEnumExtensions]
public enum GameState
{
    MainMenu,
    Playing,
    Paused,
    GameOver,
    Victory
}

public class GameManager
{
    private GameState _currentState = GameState.MainMenu;

    public bool CanProcessInput()
    {
        // 使用 IsIn 方法简化多值判断
        return _currentState.IsIn(GameState.Playing, GameState.MainMenu);
    }

    public void Update()
    {
        // 使用 IsX 方法提高可读性
        if (_currentState.IsPlaying())
        {
            UpdateGameLogic();
        }
        else if (_currentState.IsPaused())
        {
            UpdatePauseMenu();
        }
    }
}
```

### 角色状态控制

```csharp
[GenerateEnumExtensions]
public enum PlayerState
{
    Idle,
    Walking,
    Running,
    Jumping,
    Attacking
}

public class PlayerController
{
    private PlayerState _state = PlayerState.Idle;

    public bool CanAttack()
    {
        // 清晰表达可以攻击的状态
        return _state.IsIn(PlayerState.Idle, PlayerState.Walking, PlayerState.Running);
    }

    public void HandleInput(string action)
    {
        if (action == "jump" && !_state.IsJumping())
        {
            _state = PlayerState.Jumping;
        }
    }
}
```

## 限制

1. **只支持枚举类型**：不能用于类或结构体
2. **不支持 Flags 枚举的特殊处理**：对于 `[Flags]` 枚举，生成的方法仍然是简单的相等比较
3. **不生成其他方法**：只生成 IsX 和 IsIn 方法

## 相关文档

- [Source Generators 概述](./index)
- [日志生成器](./logging-generator)
- [ContextAware 生成器](./context-aware-generator)