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

SpinBox

节点继承关系

继承链：Node → CanvasItem → Control → Range → SpinBox

定义

SpinBox 是一个数字输入框——你可以直接输入数字，也可以点旁边的小箭头来增加或减少数值。就像网购时调节数量的那个控件。

使用频率：★★★ 一般常用（需要精确数值输入时使用）

节点用途

• 让用户输入或调整一个精确的数值
• 数量选择（购买数量、物品数量）
• 参数调整（窗口分辨率、音量数值）

使用场景

• 商店中调节购买数量
• 设置面板中调整分辨率
• 武器属性编辑器

常用节点搭配

• 搭配 Label 显示参数名称
• 搭配 HBoxContainer 排列参数组

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
prefix	string	""	—	数值前显示的文字（如 "$"）
suffix	string	""	—	数值后显示的文字（如 "HP"）
editable	bool	true	—	是否允许手动输入数字
update_on_keyboard_typing_finished	bool	false	—	是否在输入完成后才更新值

继承自 Range

属性	类型	默认值	继承自	说明
value	float	0.0	Range	当前值
min_value	float	0.0	Range	最小值
max_value	float	100.0	Range	最大值
step	float	1.0	Range	每次点击箭头的步进值
rounded	bool	true	Range	是否取整

信号

信号	触发时机	参数
value_changed	数值发生变化时	float 新值

常用方法

方法	说明
SetValue(float)	设置当前值
GetValue()	获取当前值
继承 Range 所有方法	—

代码示例

C

using Godot;

public partial class ShopDemo : Control
{
    public override void _Ready()
    {
        var spinBox = new SpinBox();
        spinBox.MinValue = 1;
        spinBox.MaxValue = 99;
        spinBox.Step = 1;
        spinBox.Value = 1;
        spinBox.Prefix = "数量: ";
        spinBox.Suffix = " 个";
        spinBox.Position = new Vector2(100, 100);

        spinBox.ValueChanged += (val) =>
        {
            GD.Print($"购买数量: {(int)val}");
        };

        AddChild(spinBox);
    }
}

GDScript

extends Control

func _ready():
    var spin_box = SpinBox.new()
    spin_box.min_value = 1
    spin_box.max_value = 99
    spin_box.step = 1
    spin_box.value = 1
    spin_box.prefix = "数量: "
    spin_box.suffix = " 个"
    spin_box.position = Vector2(100, 100)

    spin_box.value_changed.connect(func(val: float):
        print("购买数量: " + str(int(val)))
    )

    add_child(spin_box)