最后更新日期：2026-04-16

最后同步日期：2026-04-15 | Godot 官方原文 — @export_enum

@export_enum

定义

@export_enum 是 GDScript 中的一个注解（annotation），用来把一个变量暴露给 Godot 编辑器的检查器面板，并且以下拉菜单的形式让用户从几个预设选项中选择一个。简单说，就是给变量提供一组"选择题"——你只能从给定的选项里挑一个，不能乱填。

想象你在做一个敌人 AI，敌人有"巡逻"、"追击"、"逃跑"三种状态。用 @export_enum 就可以在编辑器里提供一个下拉菜单，策划人员点点鼠标就能切换状态，不用操心拼错单词。

在 C# 中，更推荐直接使用 enum 类型配合 [Export]，效果一样但类型更安全。

语法

C#

// C# 推荐方式：定义 enum 类型，然后用 [Export] 导出
public enum EnumEnemyState { Patrol, Chase, Flee }

[Export] public EnumEnemyState ExState = EnumEnemyState.Patrol;

// 也可以使用 PropertyHint.Enum 用字符串方式（不推荐）
[Export(PropertyHint.Enum, "Patrol,Chase,Flee")]
public int ExStateValue = 0;

GDScript

# 基本用法：列出选项，用逗号分隔
@export_enum("Patrol", "Chase", "Flee") var ex_state: String = "Patrol"

# 可以给每个选项指定对应的整数值
@export_enum("Warrior:0", "Mage:1", "Archer:2") var ex_class: int = 0

参数说明

参数	类型	必需	说明
选项列表	String...	是	一系列用逗号分隔的字符串，代表下拉菜单中的选项。每个选项可以加 :数值 后缀指定对应的整数值
变量类型	-	-	如果变量是 String 类型，存储的是选项的文本名称；如果是 int 类型，存储的是选项的索引（或自定义数值）

返回值

@export_enum 是一个注解，没有返回值。它的作用是在变量声明阶段让检查器面板显示一个下拉菜单控件。

代码示例

C#

using Godot;

public partial class Enemy : CharacterBody3D
{
    // ===== 基础用法：枚举类型导出 =====
    public enum EnumEnemyState { Patrol, Chase, Flee }
    [Export] public EnumEnemyState ExCurrentState = EnumEnemyState.Patrol;

    public enum EnumDifficulty { Easy, Normal, Hard }
    [Export] public EnumDifficulty ExDifficulty = EnumDifficulty.Normal;

    public override void _Ready()
    {
        GD.Print($"敌人状态: {ExCurrentState}，难度: {ExDifficulty}");
    }
    // 运行结果: 敌人状态: Patrol，难度: Normal


    // ===== 实际场景：角色职业系统 =====
    public enum EnumCharacterClass { Warrior = 0, Mage = 1, Archer = 2, Healer = 3 }
    [Export] public EnumCharacterClass ExClassType = EnumCharacterClass.Warrior;

    private int[] _baseAttackByClass = { 15, 8, 12, 6 };
    private int[] _baseDefenseByClass = { 12, 5, 7, 4 };

    public int GetBaseAttack()
    {
        return _baseAttackByClass[(int)ExClassType];
    }

    public void PrintStats()
    {
        int classIndex = (int)ExClassType;
        GD.Print($"职业: {ExClassType}，攻击: {_baseAttackByClass[classIndex]}，防御: {_baseDefenseByClass[classIndex]}");
    }
    // 运行结果: 职业: Warrior，攻击: 15，防御: 12


    // ===== 进阶用法：用位标志组合多个选项 =====
    [System.Flags]
    public enum EnumDamageType { None = 0, Physical = 1, Fire = 2, Ice = 4, Lightning = 8 }
    [Export] public EnumDamageType ExResistances = EnumDamageType.Fire | EnumDamageType.Ice;

    public bool IsResistantTo(EnumDamageType type)
    {
        return (ExResistances & type) != 0;
    }

    public void PrintResistances()
    {
        GD.Print($"抗性: {ExResistances}");
        GD.Print($"  抗火: {IsResistantTo(EnumDamageType.Fire)}");
        GD.Print($"  抗物理: {IsResistantTo(EnumDamageType.Physical)}");
    }
    // 运行结果: 抗性: Fire, Ice
    // 运行结果:   抗火: True
    // 运行结果:   抗物理: False
}

GDScript

extends CharacterBody3D

# ===== 基础用法：枚举导出为字符串 =====
@export_enum("Patrol", "Chase", "Flee") var ex_state: String = "Patrol"
@export_enum("Easy", "Normal", "Hard") var ex_difficulty: String = "Normal"

func _ready():
    print("敌人状态: %s，难度: %s" % [ex_state, ex_difficulty])
# 运行结果: 敌人状态: Patrol，难度: Normal


# ===== 实际场景：角色职业系统（导出为整数） =====
@export_enum("Warrior:0", "Mage:1", "Archer:2", "Healer:3") var ex_class_type: int = 0

var _base_attack_by_class := [15, 8, 12, 6]
var _base_defense_by_class := [12, 5, 7, 4]
var _class_names := ["Warrior", "Mage", "Archer", "Healer"]

func print_stats():
    print("职业: %s，攻击: %d，防御: %d" % [
        _class_names[ex_class_type],
        _base_attack_by_class[ex_class_type],
        _base_defense_by_class[ex_class_type]
    ])
# 运行结果: 职业: Warrior，攻击: 15，防御: 12


# ===== 进阶用法：多个枚举组合使用 =====
@export_enum("Sword", "Bow", "Staff", "Dagger") var ex_weapon: String = "Sword"
@export_enum("Fire", "Ice", "Lightning", "None") var ex_element: String = "None"

func get_damage_description() -> String:
    var element_text := "" if ex_element == "None" else " (%s属性)" % ex_element
    return "使用 %s%s 进行攻击" % [ex_weapon, element_text]

func print_attack():
    print(get_damage_description())
# 运行结果: 使用 Sword 进行攻击

注意事项

• @export_enum 在 GDScript 中变量类型为 String 时，存储的是选项的文本名称；类型为 int 时，存储的是选项的索引（从 0 开始），或自定义的数值。
• C# 推荐使用 enum 类型而不是字符串形式的 PropertyHint.Enum，因为 enum 有类型检查，编译器能帮你发现错误。
• 选项中可以用 名称:数值 的格式指定自定义整数值，例如 "Warrior:0,Mage:1"。
• @export_enum 只能选一个选项。如果需要多选（复选框），请使用 @export_flags。
• 修改选项列表后，已经保存在场景中的值可能失效（比如删除了某个选项），需要注意数据迁移。
• GDScript 中 @export_enum 不支持自定义类型，返回值只能是 String 或 int。如果需要更强的类型安全，建议使用 GDScript 的 enum 关键字配合 @export。