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

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

@export_group

定义

@export_group 是 GDScript 中的一个注解（annotation），用来在 Godot 编辑器的检查器面板中创建一个可折叠的分组。写在 @export_group 后面的所有导出变量都会被归入这个分组中，直到遇到下一个 @export_group 或 @export_subgroup。

简单说，当你的脚本有很多导出变量时，检查器面板会变得很长很长，找一个参数要滚动半天。@export_group 就像给变量建了"抽屉"——把相关的变量放进同一个抽屉里，需要的时候展开，不需要的时候折叠起来，界面清爽多了。

在 C# 中，对应的写法是 [ExportGroup("名称")]。

语法

C#

// 创建一个分组
[ExportGroup("Movement")]
[Export] public float ExMoveSpeed = 200f;
[Export] public float ExJumpForce = 400f;

// 创建另一个分组
[ExportGroup("Combat")]
[Export] public int ExAttackDamage = 10;

GDScript

# 创建一个分组
@export_group("Movement")
@export var ex_move_speed: float = 200.0
@export var ex_jump_force: float = 400.0

# 创建另一个分组
@export_group("Combat")
@export var ex_attack_damage: int = 10

参数说明

参数	类型	必需	说明
name	String	是	分组的名称，显示在检查器面板中
prefix	String	否	可选的变量名前缀。设置后，只有以该前缀开头的导出变量才会被归入此分组

返回值

@export_group 是一个注解，没有返回值。它的作用是在检查器面板中创建一个可视化的分组区域。

代码示例

C#

using Godot;

public partial class Player : CharacterBody3D
{
    // ===== 基础用法：创建分组 =====
    [ExportGroup("Movement")]
    [Export] public float ExMoveSpeed = 200f;
    [Export] public float ExJumpForce = 400f;
    [Export] public bool ExCanFly = false;

    public override void _Ready()
    {
        GD.Print($"移动速度: {ExMoveSpeed}，跳跃力: {ExJumpForce}，能飞: {ExCanFly}");
    }
    // 运行结果: 移动速度: 200，跳跃力: 400，能飞: False


    // ===== 实际场景：多分组管理 =====
    [ExportGroup("Health")]
    [Export] public int ExMaxHealth = 100;
    [Export] public float ExHealthRegenRate = 1.0f;

    [ExportGroup("Combat")]
    [Export] public int ExAttackDamage = 15;
    [Export] public float ExAttackSpeed = 1.5f;
    [Export] public float ExCriticalChance = 0.1f;

    [ExportGroup("Audio")]
    [Export] public AudioStream ExJumpSound;
    [Export] public AudioStream ExHurtSound;
    [Export] public AudioStream ExAttackSound;

    private int _currentHealth;

    public void TakeDamage(int amount)
    {
        _currentHealth = Mathf.Max(_currentHealth - amount, 0);
        GD.Print($"受到 {amount} 点伤害，剩余生命: {_currentHealth}/{ExMaxHealth}");
    }
    // 运行结果: 受到 20 点伤害，剩余生命: 80/100


    // ===== 进阶用法：带前缀的分组 =====
    [ExportGroup("Network", "net_")]
    [Export] public string NetServerAddress = "127.0.0.1";
    [Export] public int NetPort = 7777;
    [Export] public bool NetUseEncryption = true;

    public void PrintNetworkConfig()
    {
        GD.Print($"服务器: {NetServerAddress}:{NetPort}，加密: {NetUseEncryption}");
    }
    // 运行结果: 服务器: 127.0.0.1:7777，加密: True
}

GDScript

extends CharacterBody3D

# ===== 基础用法：创建分组 =====
@export_group("Movement")
@export var ex_move_speed: float = 200.0
@export var ex_jump_force: float = 400.0
@export var ex_can_fly: bool = false

func _ready():
    print("移动速度: %.0f，跳跃力: %.0f，能飞: %s" % [ex_move_speed, ex_jump_force, ex_can_fly])
# 运行结果: 移动速度: 200，跳跃力: 400，能飞: False


# ===== 实际场景：多分组管理 =====
@export_group("Health")
@export var ex_max_health: int = 100
@export var ex_health_regen_rate: float = 1.0

@export_group("Combat")
@export var ex_attack_damage: int = 15
@export var ex_attack_speed: float = 1.5
@export var ex_critical_chance: float = 0.1

@export_group("Audio")
@export var ex_jump_sound: AudioStream
@export var ex_hurt_sound: AudioStream
@export var ex_attack_sound: AudioStream

var _current_health: int

func take_damage(amount: int):
    _current_health = maxi(_current_health - amount, 0)
    print("受到 %d 点伤害，剩余生命: %d/%d" % [amount, _current_health, ex_max_health])
# 运行结果: 受到 20 点伤害，剩余生命: 80/100


# ===== 进阶用法：带前缀的分组 =====
@export_group("Network", "net_")
@export var net_server_address: String = "127.0.0.1"
@export var net_port: int = 7777
@export var net_use_encryption: bool = true

func print_network_config():
    print("服务器: %s:%d，加密: %s" % [net_server_address, net_port, net_use_encryption])
# 运行结果: 服务器: 127.0.0.1:7777，加密: True

注意事项

• @export_group 后面的所有导出变量都会被归入该分组，直到遇到下一个 @export_group 或脚本结束。
• 分组在检查器面板中是可折叠的，用户可以展开或折叠来管理显示空间。
• 使用 prefix 参数可以自动过滤：只有变量名以该前缀开头的变量才会显示在分组中，其他变量会被排除。
• 分组名称会原样显示在检查器中，建议使用简洁有意义的英文名称。
• @export_group 不影响变量的实际功能，纯粹是编辑器界面组织工具。
• 可以和 @export_subgroup 搭配使用，在分组内部再创建子分组。
• C# 中使用 [ExportGroup("名称")] 或 [ExportGroup("名称", "前缀")] 的形式。