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

枚举扩展生成器

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

概述

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

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

基础使用

using GFramework.SourceGenerators.Abstractions.Enums;

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

生成的代码

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

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

使用示例

var state = GameState.Paused;

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

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

配置选项

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

[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 扩展方法

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

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

只生成 IsX 方法

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

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

只生成 IsIn 方法

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

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

最佳实践

1. 命名约定

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

• Normal → IsNormal()
• GameOver → IsGameOver()
• HTTP_ERROR → IsHTTP_ERROR()

2. 性能考虑

生成的方法是内联的，性能与手写代码相同：

// 生成的代码
public static bool IsNormal(this GameState value)
    => value == GameState.Normal;

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

3. 可读性提升

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

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

实际应用示例

游戏状态管理

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

角色状态控制

[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 概述
• 日志生成器
• ContextAware 生成器