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

Range

节点继承关系

继承链：Node → CanvasItem → Control → Range

Control

类型	名称	说明
属性	Size	控件尺寸
属性	Position	控件位置
属性	AnchorsPreset	锚点预设
属性	GrowDirection	超出容器时的扩展方向
属性	MouseFilter	鼠标事件过滤（停止 / 通过 / 忽略）
属性	FocusMode	焦点模式（无 / 单击 / 全部）
信号	gui_input	接收到 GUI 输入事件
信号	mouse_entered	鼠标进入控件区域
信号	mouse_exited	鼠标离开控件区域
信号	focus_entered	获得焦点
信号	focus_exited	失去焦点
信号	resized	尺寸变化
方法	GrabFocus()	获取焦点
方法	ReleaseFocus()	释放焦点
方法	SetAnchorsPreset()	设置锚点预设
方法	GetMinimumSize()	获取最小尺寸

CanvasItem

类型	名称	说明
属性	Visible	是否可见
属性	Modulate	整体颜色叠加（乘法）
属性	SelfModulate	自身颜色叠加（不影响子节点）
属性	ZIndex	绘制层级（Z 轴排序）
信号	visibility_changed	可见性变化时触发
方法	GetGlobalMousePosition()	获取鼠标全局坐标

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

Range 是数值范围的抽象基类。它定义了一个"有最小值、最大值、当前值"的框架。所有需要表示数值范围的控件都继承自它——进度条、滑动条、数值输入框等。就像一个"尺子"的模板——尺子有刻度（min/max），有当前位置（value），但你可以用不同的方式展示这把尺子（进度条、滑块、数字框）。

使用频率：★★★★ 维度专用常用（通过子类间接使用，非常频繁）

节点用途

• 作为所有数值范围控件的基类
• 定义 min/max/value 框架

使用场景

• 不直接使用，请使用具体的子类

常用节点搭配

所有数值范围控件都是它的子类：

• ProgressBar — 进度条
• TextureProgressBar — 图片进度条
• Slider — 滑动条
• HSlider — 水平滑动条
• VSlider — 垂直滑动条
• SpinBox — 数值输入框
• ScrollBar — 滚动条
• HScrollBar — 水平滚动条
• VScrollBar — 垂直滚动条

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
min_value	float	0.0	—	最小值
max_value	float	100.0	—	最大值
value	float	0.0	—	当前值
step	float	1.0	—	步进值（每次变化的量）
page	float	0.0	—	页大小（用于滚动条）
ratio	float	0.0	—	当前值在范围中的比例（只读，0~1）
rounded	bool	false	—	是否将值取整
exp_ratio	bool	false	—	是否使用指数比例

信号

信号	触发时机	参数
value_changed	值发生变化时	float 新值
min_value_changed	最小值变化时	float 新最小值
max_value_changed	最大值变化时	float 新最大值

常用方法

方法	说明
SetValue(float)	设置当前值
GetValue()	获取当前值
SetMinValue(float)	设置最小值
SetMaxValue(float)	设置最大值
GetRatio()	获取当前比例（0~1）
SetRatio(float)	通过比例设置值
Share(Node)	与另一个 Range 共享值

代码示例

C

// Range 是抽象基类，请使用具体子类
// 示例参考 ProgressBar、Slider、SpinBox 等页面

GDScript

# Range 是抽象基类，请使用具体子类
# 示例参考 ProgressBar、Slider、SpinBox 等页面