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

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

@export_subgroup

定义

@export_subgroup 是 GDScript 中的一个注解（annotation），用来在 Godot 编辑器的检查器面板中，在已有的 @export_group 分组内部创建一个更小的子分组。它提供了一层额外的层级组织，让你把相关的变量分得更细。

简单说，@export_group 是大抽屉，@export_subgroup 是大抽屉里的小隔板。比如"战斗"大分组里可以再分"近战武器"和"远程武器"两个子分组，让界面更有条理。

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

语法

C#

[ExportGroup("Combat")]
[ExportSubgroup("Melee")]
[Export] public int ExMeleeDamage = 10;
[Export] public float ExMeleeRange = 1.5f;

[ExportSubgroup("Ranged")]
[Export] public int ExRangedDamage = 8;
[Export] public float ExRangedRange = 10.0f;

GDScript

@export_group("Combat")
@export_subgroup("Melee")
@export var ex_melee_damage: int = 10
@export var ex_melee_range: float = 1.5

@export_subgroup("Ranged")
@export var ex_ranged_damage: int = 8
@export var ex_ranged_range: float = 10.0

参数说明

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

返回值

@export_subgroup 是一个注解，没有返回值。它的作用是在检查器面板的当前分组内部创建一个子分组。

代码示例

C#

using Godot;

public partial class Enemy : CharacterBody3D
{
    // ===== 基础用法：在分组内创建子分组 =====
    [ExportGroup("Movement")]
    [ExportSubgroup("Walking")]
    [Export] public float ExWalkSpeed = 100f;

    [ExportSubgroup("Running")]
    [Export] public float ExRunSpeed = 250f;
    [Export] public float ExRunStaminaCost = 10f;

    public override void _Ready()
    {
        GD.Print($"走路速度: {ExWalkSpeed}，跑步速度: {ExRunSpeed}");
    }
    // 运行结果: 走路速度: 100，跑步速度: 250


    // ===== 实际场景：完整的角色配置面板 =====
    [ExportGroup("Stats")]
    [ExportSubgroup("Offensive")]
    [Export] public int ExAttackPower = 20;
    [Export] public float ExAttackSpeed = 1.2f;
    [Export] public float ExCriticalChance = 0.15f;

    [ExportSubgroup("Defensive")]
    [Export] public int ExDefense = 10;
    [Export] public float ExDodgeChance = 0.1f;
    [Export] public int ExShieldPoints = 50;

    [ExportGroup("AI")]
    [ExportSubgroup("Detection")]
    [Export] public float ExSightRange = 15.0f;
    [Export] public float ExSightAngle = 90.0f;

    [ExportSubgroup("Patrol")]
    [Export] public float ExPatrolSpeed = 60f;
    [Export] public float ExWaitTime = 2.0f;

    public void PrintStats()
    {
        GD.Print($"攻击: {ExAttackPower}，防御: {ExDefense}，视野: {ExSightRange}m");
    }
    // 运行结果: 攻击: 20，防御: 10，视野: 15m


    // ===== 进阶用法：带前缀的子分组 =====
    [ExportGroup("Visual")]
    [ExportSubgroup("Colors", "color_")]
    [Export] public Color ColorBody = Colors.White;
    [Export] public Color ColorOutline = Colors.Black;

    [ExportSubgroup("Effects", "fx_")]
    [Export] public bool FxGlowEnabled = true;
    [Export] public float FxGlowIntensity = 1.0f;

    public void PrintVisualConfig()
    {
        GD.Print($"发光: {FxGlowEnabled}，强度: {FxGlowIntensity}");
    }
    // 运行结果: 发光: True，强度: 1
}

GDScript

extends CharacterBody3D

# ===== 基础用法：在分组内创建子分组 =====
@export_group("Movement")
@export_subgroup("Walking")
@export var ex_walk_speed: float = 100.0

@export_subgroup("Running")
@export var ex_run_speed: float = 250.0
@export var ex_run_stamina_cost: float = 10.0

func _ready():
    print("走路速度: %.0f，跑步速度: %.0f" % [ex_walk_speed, ex_run_speed])
# 运行结果: 走路速度: 100，跑步速度: 250


# ===== 实际场景：完整的角色配置面板 =====
@export_group("Stats")
@export_subgroup("Offensive")
@export var ex_attack_power: int = 20
@export var ex_attack_speed: float = 1.2
@export var ex_critical_chance: float = 0.15

@export_subgroup("Defensive")
@export var ex_defense: int = 10
@export var ex_dodge_chance: float = 0.1
@export var ex_shield_points: int = 50

@export_group("AI")
@export_subgroup("Detection")
@export var ex_sight_range: float = 15.0
@export var ex_sight_angle: float = 90.0

@export_subgroup("Patrol")
@export var ex_patrol_speed: float = 60.0
@export var ex_wait_time: float = 2.0

func print_stats():
    print("攻击: %d，防御: %d，视野: %.0fm" % [ex_attack_power, ex_defense, ex_sight_range])
# 运行结果: 攻击: 20，防御: 10，视野: 15m


# ===== 进阶用法：带前缀的子分组 =====
@export_group("Visual")
@export_subgroup("Colors", "color_")
@export var color_body: Color = Color.WHITE
@export var color_outline: Color = Color.BLACK

@export_subgroup("Effects", "fx_")
@export var fx_glow_enabled: bool = true
@export var fx_glow_intensity: float = 1.0

func print_visual_config():
    print("发光: %s，强度: %.1f" % [fx_glow_enabled, fx_glow_intensity])
# 运行结果: 发光: True，强度: 1.0

注意事项

• @export_subgroup 必须在 @export_group 之后使用，不能单独出现。如果前面没有分组，子分组会出现在默认区域。
• 子分组是在分组内部的二级层级，提供更细粒度的组织。
• @export_subgroup 后面的变量都属于该子分组，直到遇到下一个 @export_group 或 @export_subgroup。
• prefix 参数和 @export_group 的 prefix 功能一致：只有变量名以该前缀开头的变量才会归入子分组。
• 子分组不影响变量的实际功能，纯粹是编辑器界面组织工具。
• C# 中使用 [ExportSubgroup("名称")] 或 [ExportSubgroup("名称", "前缀")] 的形式。