Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

SpinBox

继承： Range < Control < CanvasItem < Node < Object

数字的输入字段。

描述

SpinBox（数值调节框）是一个用于输入数字的文本框。它允许用户输入整数和浮点数（小数）。SpinBox 还带有上、下按钮，点击它们可以增加或减少数值。此外，在 SpinBox 的箭头区域按住鼠标上下拖动，也可以改变数值。

另外，它还可以直接输入数学表达式。当用户在编辑 SpinBox 文本框时按下 Enter（回车键），这些表达式就会被自动计算。这是通过 Expression 类来解析和求值的，计算得出的结果会被直接设为 SpinBox 的当前值。一些有效的表达式示例包括：5 + 2 * 3、pow(2, 4) 以及 PI + sin(0.5)。需要注意的是，表达式是区分大小写的。

示例： 创建一个 SpinBox，禁用它的右键上下文菜单，并将其文本对齐方式设置为右对齐。

var spin_box = SpinBox.new()
add_child(spin_box)
var line_edit = spin_box.get_line_edit()
line_edit.context_menu_enabled = false
spin_box.horizontal_alignment = LineEdit.HORIZONTAL_ALIGNMENT_RIGHT

var spinBox = new SpinBox();
AddChild(spinBox);
var lineEdit = spinBox.GetLineEdit();
lineEdit.ContextMenuEnabled = false;
spinBox.AlignHorizontal = LineEdit.HorizontalAlignEnum.Right;

请参阅 Range（范围）类，了解 SpinBox 的更多选项。

注意： 如果禁用了 SpinBox 的上下文菜单（右键菜单），你可以在数值调节框的下半部分点击右键，将值设为其最小值；而在上半部分点击右键，则会将值设为其最大值。

注意： SpinBox 底层依赖于一个 LineEdit（单行文本框）节点。如果想要修改 SpinBox 的背景主题，需要添加并自定义 LineEdit 的主题项。该 LineEdit 带有 SpinBoxInnerLineEdit 主题变体，这样你就可以让它拥有区别于普通 LineEdit 的独特外观。

注意： 如果你想为底层的 LineEdit 实现拖放（Drag and Drop）功能，可以在 get_line_edit() 方法返回的节点上使用 Control.set_drag_forwarding()。

属性

HorizontalAlignment	alignment	`0`
bool	custom_arrow_round	`false`
float	custom_arrow_step	`0.0`
bool	editable	`true`
String	prefix	`""`
bool	select_all_on_focus	`false`
BitField[SizeFlags]	size_flags_vertical	`1` (overrides Control)
float	step	`1.0` (overrides Range)
String	suffix	`""`
bool	update_on_text_changed	`false`

方法

void	apply()
LineEdit	get_line_edit()

主题属性

Color	down_disabled_icon_modulate	`Color(0.875, 0.875, 0.875, 0.5)`
Color	down_hover_icon_modulate	`Color(0.95, 0.95, 0.95, 1)`
Color	down_icon_modulate	`Color(0.875, 0.875, 0.875, 1)`
Color	down_pressed_icon_modulate	`Color(0.95, 0.95, 0.95, 1)`
Color	up_disabled_icon_modulate	`Color(0.875, 0.875, 0.875, 0.5)`
Color	up_hover_icon_modulate	`Color(0.95, 0.95, 0.95, 1)`
Color	up_icon_modulate	`Color(0.875, 0.875, 0.875, 1)`
Color	up_pressed_icon_modulate	`Color(0.95, 0.95, 0.95, 1)`
int	buttons_vertical_separation	`0`
int	buttons_width	`16`
int	field_and_buttons_separation	`2`
int	set_min_buttons_width_from_icons	`1`
Texture2D	down
Texture2D	down_disabled
Texture2D	down_hover
Texture2D	down_pressed
Texture2D	up
Texture2D	up_disabled
Texture2D	up_hover
Texture2D	up_pressed
Texture2D	updown
StyleBox	down_background
StyleBox	down_background_disabled
StyleBox	down_background_hovered
StyleBox	down_background_pressed
StyleBox	field_and_buttons_separator
StyleBox	up_background
StyleBox	up_background_disabled
StyleBox	up_background_hovered
StyleBox	up_background_pressed
StyleBox	up_down_buttons_separator

属性说明

HorizontalAlignment alignment = 0 🔗

void set_horizontal_alignment(value: HorizontalAlignment)
HorizontalAlignment get_horizontal_alignment()

更改底层 LineEdit 的对齐方式。

bool custom_arrow_round = false 🔗

void set_custom_arrow_round(value: bool)
bool is_custom_arrow_rounding()

如果为 true，则与箭头按钮交互时，该值将四舍五入为 custom_arrow_step 的倍数。否则，值将增加 custom_arrow_step，然后根据 Range.step 进行四舍五入。

float custom_arrow_step = 0.0 🔗

void set_custom_arrow_step(value: float)
float get_custom_arrow_step()

如果不是 0，则设置与 SpinBox 的箭头按钮交互时的步长。

注意：Range.value 仍然会舍入到 Range.step 的倍数。

bool editable = true 🔗

void set_editable(value: bool)
bool is_editable()

如果为 true，则 SpinBox 将是可编辑的。否则，它将是只读的。

String prefix = "" 🔗

void set_prefix(value: String)
String get_prefix()

在 SpinBox 的数值前添加指定的前缀字符串。

bool select_all_on_focus = false 🔗

void set_select_all_on_focus(value: bool)
bool is_select_all_on_focus()

如果为 true，则该 SpinBox 会在 LineEdit 获得焦点时选中整个文本。点击上下箭头不会触发这种行为。

String suffix = "" 🔗

void set_suffix(value: String)
String get_suffix()

在 SpinBox 的数值后添加指定的后缀字符串。

bool update_on_text_changed = false 🔗

void set_update_on_text_changed(value: bool)
bool get_update_on_text_changed()

设置该 SpinBox 的 Range 值在 LineEdit 文本发生改变时更新，不再在提交时更新。见 LineEdit.text_changed 和 LineEdit.text_submitted。

注意：如果设置为 true，会影响在 SpinBox 中输入数学表达式。SpinBox 会在你打字时尝试对表达式求值，因此，部分符号会因为表达式求值而被立即移除，例如末尾的 + 号。

方法说明

void apply() 🔗

应用 SpinBox 的当前值。等价于在 SpinBox 所使用的 LineEdit 中进行编辑时按下 Enter 键。会导致发出 LineEdit.text_submitted、对当前所包含的表达式进行求值。

LineEdit get_line_edit() 🔗

返回这个 SpinBox 中的 LineEdit 实例。你可以用它来访问 LineEdit 的属性和方法。

警告：这是一个必要的内部节点，移除和释放它可能会导致崩溃。如果你想隐藏它或它的任何子节点，请使用其 CanvasItem.visible 属性。

主题属性说明

Color down_disabled_icon_modulate = Color(0.875, 0.875, 0.875, 0.5) 🔗

向下按钮处于禁用状态时的图标调制颜色。

Color down_hover_icon_modulate = Color(0.95, 0.95, 0.95, 1) 🔗

向下按钮处于悬停状态时的图标调制颜色。

Color down_icon_modulate = Color(0.875, 0.875, 0.875, 1) 🔗

向下按钮的图标调制颜色。

Color down_pressed_icon_modulate = Color(0.95, 0.95, 0.95, 1) 🔗

向下按钮处于按下状态时的图标调制颜色。

Color up_disabled_icon_modulate = Color(0.875, 0.875, 0.875, 0.5) 🔗

向上按钮处于禁用状态时的图标调制颜色。

Color up_hover_icon_modulate = Color(0.95, 0.95, 0.95, 1) 🔗

向上按钮处于悬停状态时的图标调制颜色。

Color up_icon_modulate = Color(0.875, 0.875, 0.875, 1) 🔗

向上按钮的图标调制颜色。

Color up_pressed_icon_modulate = Color(0.95, 0.95, 0.95, 1) 🔗

向上按钮处于按下状态时的图标调制颜色。

int buttons_vertical_separation = 0 🔗

上下按钮之间的垂直间隔。

int buttons_width = 16 🔗

上下按钮的宽度。如果小于按钮上设置的图标，那么对应的图标就可能与相邻的元素重叠。如果小于 0，那么就会根据图标的大小自动调整宽度。

int field_and_buttons_separation = 2 🔗

文本输入框（LineEdit）与按钮之间的水平间隔宽度。

int set_min_buttons_width_from_icons = 1 🔗

如果非 0，则最小按钮宽度对应这些按钮所设置的最宽的图标，即便 buttons_width 更小。

Texture2D down 🔗

向下按钮的图标，在下按钮（减小取值）的中间显示。

Texture2D down_disabled 🔗

向下按钮禁用时的图标。

Texture2D down_hover 🔗

向下按钮悬停时的图标。

Texture2D down_pressed 🔗

向下按钮按下时的图标。

Texture2D up 🔗

向上按钮的图标，在上按钮（增加取值）的中间显示。

Texture2D up_disabled 🔗

向上按钮禁用时的图标。

Texture2D up_hover 🔗

向上按钮悬停时的图标。

Texture2D up_pressed 🔗

向上按钮按下时的图标。

Texture2D updown 🔗

代表上下按钮图标的单个纹理。该纹理显示在按钮中间，交互式不会改变。分配有效的图标后会代替 up 和 down。

StyleBox down_background 🔗

向下按钮的背景样式。

StyleBox down_background_disabled 🔗

向下按钮禁用时的背景样式。

StyleBox down_background_hovered 🔗

向下按钮悬停时的背景样式。

StyleBox down_background_pressed 🔗

向下按钮按下时的背景样式。

StyleBox field_and_buttons_separator 🔗

输入框和按钮之间的间隔区域内绘制的 StyleBox。

StyleBox up_background 🔗

向上按钮的背景样式。

StyleBox up_background_disabled 🔗

向上按钮禁用时的背景样式。

StyleBox up_background_hovered 🔗

向上按钮悬停时的背景样式。

StyleBox up_background_pressed 🔗

向上按钮按下时的背景样式。

StyleBox up_down_buttons_separator 🔗

上下按钮之间的间隔区域内绘制的 StyleBox。