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

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

@export_range

定义

@export_range 是 GDScript 中的一个注解（annotation），用来把一个数字变量暴露给 Godot 编辑器的检查器面板，并且限制它只能在一个指定的范围内取值。简单说，就是给数字加了个"栏杆"——你不能输入超出范围的值。

想象你在调角色的移动速度，如果有人不小心输入了 -999 或 99999，游戏就炸了。@export_range 就像给输入框装了"限位器"，只允许在合理范围内调整。编辑器里会出现一个滑块（slider），你可以拖动滑块选择值，也可以直接输入。

在 C# 中，对应的写法是 [Export(PropertyHint.Range, "min,max,step")]。

语法

C#

// 基本范围导出：最小值, 最大值
[Export(PropertyHint.Range, "0,100")]
public int ExHealth = 100;

// 带步长的范围导出：最小值, 最大值, 步长
[Export(PropertyHint.Range, "0.0,1.0,0.1")]
public float ExVolume = 0.5f;

// 带额外标志的范围导出
[Export(PropertyHint.Range, "0,360,1,radians_as_degrees")]
public float ExRotationAngle = 0f;

GDScript

# 基本范围导出：最小值, 最大值
@export_range(0, 100) var ex_health: int = 100

# 带步长的范围导出：最小值, 最大值, 步长
@export_range(0.0, 1.0, 0.1) var ex_volume: float = 0.5

# 带额外标志的范围导出
@export_range(0, 360, 1, "radians_as_degrees") var ex_rotation_angle: float = 0.0

参数说明

参数	类型	必需	说明
min	float	是	范围的最小值，滑块的最左端
max	float	是	范围的最大值，滑块的最右端
step	float	否	步长，即每次拖动滑块变化的幅度。默认为 1.0。如果需要精确到小数点后一位，可以设为 0.1
"or_greater"	String	否	额外提示字符串。加上后，编辑器允许输入超过 max 的值
"or_less"	String	否	额外提示字符串。加上后，编辑器允许输入低于 min 的值
"exp"	String	否	额外提示字符串。让滑块使用指数分布，更适合需要精细控制小值的场景（如音量）
"radians_as_degrees"	String	否	额外提示字符串。编辑器中显示为角度（度），但实际存储和代码中使用弧度
"degrees"	String	否	额外提示字符串。将值标记为角度值，配合编辑器的角度显示
"hide_slider"	String	否	额外提示字符串。隐藏滑块，只显示数字输入框
"no_slider"	String	否	额外提示字符串。与 hide_slider 相同，隐藏滑块控件

返回值

@export_range 是一个注解，没有返回值。它的作用是在变量声明阶段修改编辑器的显示方式，让检查器面板中出现一个带范围限制的滑块控件。

代码示例

C#

using Godot;

public partial class Player : CharacterBody3D
{
    // ===== 基础用法：限制数值范围 =====
    [Export(PropertyHint.Range, "0,100")]
    public int ExHealth = 100;

    [Export(PropertyHint.Range, "0.0,10.0,0.1")]
    public float ExMoveSpeed = 5.0f;

    public override void _Ready()
    {
        GD.Print($"生命值: {ExHealth}, 移动速度: {ExMoveSpeed}");
    }
    // 运行结果: 生命值: 100, 移动速度: 5


    // ===== 实际场景：角色属性配置 =====
    [Export(PropertyHint.Range, "1,99")]
    public int ExLevel = 1;

    [Export(PropertyHint.Range, "0.0,1.0,0.01")]
    public float ExCriticalRate = 0.1f;

    [Export(PropertyHint.Range, "0.0,1.0,0.01,exp")]
    public float ExVolume = 0.5f;

    [Export(PropertyHint.Range, "0,1000,10,or_greater")]
    public int ExMaxExperience = 100;

    public void LevelUp()
    {
        ExLevel = Mathf.Min(ExLevel + 1, 99);
        GD.Print($"升级了！当前等级: {ExLevel}，暴击率: {ExCriticalRate * 100}%");
    }
    // 运行结果: 升级了！当前等级: 2，暴击率: 10%


    // ===== 进阶用法：角度与弧度转换 =====
    [Export(PropertyHint.Range, "0,360,1,radians_as_degrees")]
    public float ExFieldOfView = 1.047f; // 60度 ≈ 1.047弧度

    [Export(PropertyHint.Range, "-180,180,0.1,degrees")]
    public float ExRotation = 0.0f;

    public void PrintAngles()
    {
        GD.Print($"视野角度(弧度): {ExFieldOfView}，约等于 {Mathf.RadToDeg(ExFieldOfView)} 度");
        GD.Print($"旋转角度: {ExRotation} 度");
    }
    // 运行结果: 视野角度(弧度): 1.047，约等于 60 度
    // 运行结果: 旋转角度: 0 度
}

GDScript

extends CharacterBody3D

# ===== 基础用法：限制数值范围 =====
@export_range(0, 100) var ex_health: int = 100
@export_range(0.0, 10.0, 0.1) var ex_move_speed: float = 5.0

func _ready():
    print("生命值: %d, 移动速度: %.1f" % [ex_health, ex_move_speed])
# 运行结果: 生命值: 100, 移动速度: 5.0


# ===== 实际场景：角色属性配置 =====
@export_range(1, 99) var ex_level: int = 1
@export_range(0.0, 1.0, 0.01) var ex_critical_rate: float = 0.1
@export_range(0.0, 1.0, 0.01, "exp") var ex_volume: float = 0.5
@export_range(0, 1000, 10, "or_greater") var ex_max_experience: int = 100

func level_up():
    ex_level = mini(ex_level + 1, 99)
    print("升级了！当前等级: %d，暴击率: %.0f%%" % [ex_level, ex_critical_rate * 100])
# 运行结果: 升级了！当前等级: 2，暴击率: 10%


# ===== 进阶用法：角度与弧度转换 =====
@export_range(0, 360, 1, "radians_as_degrees") var ex_field_of_view: float = 1.047
@export_range(-180, 180, 0.1, "degrees") var ex_rotation: float = 0.0

func print_angles():
    print("视野角度(弧度): %.3f，约等于 %.0f 度" % [ex_field_of_view, rad_to_deg(ex_field_of_view)])
    print("旋转角度: %.1f 度" % ex_rotation)
# 运行结果: 视野角度(弧度): 1.047，约等于 60 度
# 运行结果: 旋转角度: 0.0 度

注意事项

• @export_range 只能用于 int 和 float 类型的变量，对其他类型无效。
• 步长（step） 是可选的，但当你需要精确控制小数时（比如 0.01 步长），必须显式指定。
• or_greater 和 or_less 标志允许突破范围限制，但滑块仍然只在指定范围内，超出部分需要手动输入。
• exp 标志改变滑块的行为为指数分布，适合音量、透明度等人类感知是对数关系的场景。
• radians_as_degrees 非常有用：编辑器里显示"度"（人类友好），代码里用"弧度"（Godot 引擎标准），自动完成转换。
• C# 中使用 [Export(PropertyHint.Range, "min,max,step,hint")] 的形式，提示字符串用逗号分隔。
• 多个额外提示可以同时使用，例如 "0.0,1.0,0.01,exp,or_greater"。