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

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

@export_flags

定义

@export_flags 是 GDScript 中的一个注解（annotation），用来在 Godot 编辑器的检查器面板中暴露一组复选框控件，允许用户同时选择多个选项。每个选项对应一个"位标志"（bit flag），可以用按位运算组合在一起。

简单说，@export_enum 是单选题（下拉菜单只能选一个），@export_flags 是多选题（复选框可以勾选多个）。比如你的角色可以同时拥有"飞行"、"游泳"、"隐身"等多种能力，用 @export_flags 就能在编辑器里勾选多个能力。

在 C# 中，推荐使用带 [System.Flags] 特性的 enum 类型配合 [Export]。

语法

C#

// C# 推荐方式：使用 Flags 枚举
[System.Flags]
public enum EnumAbility { None = 0, Fly = 1, Swim = 2, Invisible = 4 }

[Export] public EnumAbility ExAbilities = EnumAbility.None;

// 也可以使用 PropertyHint.Flags（不推荐）
[Export(PropertyHint.Flags, "Fly,Swim,Invisible")]
public int ExAbilityFlags = 0;

GDScript

# 基本用法：列出选项，用逗号分隔
@export_flags("Fly", "Swim", "Invisible") var ex_abilities: int = 0

# 也可以用冒号指定自定义位值
@export_flags("Fire:1", "Ice:2", "Lightning:4", "Poison:8") var ex_elements: int = 0

参数说明

参数	类型	必需	说明
选项列表	String...	是	一系列用逗号分隔的字符串选项。每个选项在内部对应一个位值（1, 2, 4, 8, 16...），也可以用 名称:值 手动指定
变量类型	-	-	必须是 int 类型，存储的是所有选中选项的位组合值

返回值

@export_flags 是一个注解，没有返回值。变量的值是一个整数，是所有选中选项对应的位值之和。

代码示例

C#

using Godot;

public partial class Character : CharacterBody3D
{
    // ===== 基础用法：Flags 枚举 =====
    [System.Flags]
    public enum EnumAbility { None = 0, Fly = 1, Swim = 2, Invisible = 4, Dash = 8 }
    [Export] public EnumAbility ExAbilities = EnumAbility.None;

    public override void _Ready()
    {
        GD.Print($"能力: {ExAbilities} (值: {(int)ExAbilities})");
    }
    // 运行结果: 能力: Fly, Swim (值: 3)


    // ===== 实际场景：碰撞层/掩码配置 =====
    [System.Flags]
    public enum EnumCollisionLayer { Player = 1, Enemy = 2, Bullet = 4, Item = 8 }
    [Export] public EnumCollisionLayer ExTargetLayers = EnumCollisionLayer.Enemy | EnumCollisionLayer.Item;

    public bool CanTarget(EnumCollisionLayer layer)
    {
        return (ExTargetLayers & layer) != 0;
    }

    public void PrintTargetInfo()
    {
        GD.Print($"目标层: {ExTargetLayers}");
        GD.Print($"  可以瞄准敌人: {CanTarget(EnumCollisionLayer.Enemy)}");
        GD.Print($"  可以瞄准玩家: {CanTarget(EnumCollisionLayer.Player)}");
        GD.Print($"  可以瞄准物品: {CanTarget(EnumCollisionLayer.Item)}");
    }
    // 运行结果: 目标层: Enemy, Item
    // 运行结果:   可以瞄准敌人: True
    // 运行结果:   可以瞄准玩家: False
    // 运行结果:   可以瞄准物品: True


    // ===== 进阶用法：权限系统 =====
    [System.Flags]
    public enum EnumPermission { Read = 1, Write = 2, Execute = 4, Admin = 8 }
    [Export] public EnumPermission ExUserPermissions = EnumPermission.Read | EnumPermission.Write;

    public bool HasPermission(EnumPermission perm)
    {
        return (ExUserPermissions & perm) != 0;
    }

    public void GrantPermission(EnumPermission perm)
    {
        ExUserPermissions |= perm;
        GD.Print($"已授权 {perm}，当前权限: {ExUserPermissions}");
    }

    public void RevokePermission(EnumPermission perm)
    {
        ExUserPermissions &= ~perm;
        GD.Print($"已撤销 {perm}，当前权限: {ExUserPermissions}");
    }

    public void DemoPermissions()
    {
        GrantPermission(EnumPermission.Execute);
        RevokePermission(EnumPermission.Write);
    }
    // 运行结果: 已授权 Execute，当前权限: Read, Write, Execute
    // 运行结果: 已撤销 Write，当前权限: Read, Execute
}

GDScript

extends CharacterBody3D

# ===== 基础用法：导出标志位 =====
@export_flags("Fly", "Swim", "Invisible", "Dash") var ex_abilities: int = 0

func _ready():
    var ability_names := []
    if ex_abilities & 1: ability_names.append("Fly")
    if ex_abilities & 2: ability_names.append("Swim")
    if ex_abilities & 4: ability_names.append("Invisible")
    if ex_abilities & 8: ability_names.append("Dash")
    print("能力: %s (值: %d)" % [", ".join(ability_names), ex_abilities])
# 运行结果: 能力: Fly, Swim (值: 3)


# ===== 实际场景：碰撞层配置 =====
@export_flags("Player:1", "Enemy:2", "Bullet:4", "Item:8") var ex_target_layers: int = 10  # Enemy + Item

func can_target(layer: int) -> bool:
    return (ex_target_layers & layer) != 0

func print_target_info():
    print("目标层值: %d" % ex_target_layers)
    print("  可以瞄准敌人: %s" % can_target(2))
    print("  可以瞄准玩家: %s" % can_target(1))
    print("  可以瞄准物品: %s" % can_target(8))
# 运行结果: 目标层值: 10
# 运行结果:   可以瞄准敌人: True
# 运行结果:   可以瞄准玩家: False
# 运行结果:   可以瞄准物品: True


# ===== 进阶用法：自定义位值权限系统 =====
@export_flags("Read:1", "Write:2", "Execute:4", "Admin:8") var ex_user_permissions: int = 3  # Read + Write

func has_permission(perm: int) -> bool:
    return (ex_user_permissions & perm) != 0

func grant_permission(perm: int):
    ex_user_permissions = ex_user_permissions | perm
    print("已授权，当前权限值: %d" % ex_user_permissions)

func revoke_permission(perm: int):
    ex_user_permissions = ex_user_permissions & ~perm
    print("已撤销，当前权限值: %d" % ex_user_permissions)

func demo_permissions():
    grant_permission(4)   # Execute
    revoke_permission(2)  # Write
# 运行结果: 已授权，当前权限值: 7
# 运行结果: 已撤销，当前权限值: 5

注意事项

• @export_flags 只能用于 int 类型的变量。
• 每个选项自动分配一个位值（1, 2, 4, 8, 16...），你也可以用 名称:值 手动指定。自定义值必须是 2 的幂次（1, 2, 4, 8...），否则位运算会出错。
• 最多支持 32 个选项（因为 int 类型最多 32 位标志）。
• 检查一个标志是否被设置，用按位与运算：(flags & value) != 0。
• 设置一个标志，用按位或运算：flags |= value。
• 清除一个标志，用按位与取反运算：flags &= ~value。
• C# 推荐使用 [System.Flags] 枚举类型，比直接操作整数更安全和可读。
• @export_flags 用于多选场景。如果只需要单选，请使用 @export_enum。