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

CheckButton

节点继承关系

继承链：Node → CanvasItem → Control → BaseButton → CheckButton

定义

和 CheckBox 功能几乎一样，但外观是那种"滑动开关"的样子——就像手机设置里的开关按钮，拨一下开、再拨一下关。功能上与 CheckBox 完全相同，只是视觉样式不同。

使用频率：★★★ 一般常用（设置面板中常见，比 CheckBox 更现代）

节点用途

• 二选一的开关设置
• 功能的启用/禁用切换

使用场景

• 游戏设置中的"夜间模式"、"振动反馈"开关
• 音频设置中的"音效"、"音乐"开关

常用节点搭配

• 搭配 VBoxContainer 排列多个开关
• 搭配 Label 显示说明文字

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
text	string	""	—	开关旁边的文字

继承自 BaseButton

属性	类型	默认值	继承自	说明
button_pressed	bool	false	BaseButton	是否开启
disabled	bool	false	BaseButton	是否禁用

信号

信号	触发时机	参数
toggled	开关状态变化时	bool 是否开启
pressed	被点击时	无

常用方法

继承自 BaseButton 的所有方法。

代码示例

C

using Godot;

public partial class CheckButtonDemo : Control
{
    public override void _Ready()
    {
        var toggle = new CheckButton();
        toggle.Text = "夜间模式";
        toggle.Position = new Vector2(100, 100);

        toggle.Toggled += (isOn) =>
        {
            GD.Print($"夜间模式：{(isOn ? "开" : "关")}");
        };

        AddChild(toggle);
    }
}

GDScript

extends Control

func _ready():
    var toggle = CheckButton.new()
    toggle.text = "夜间模式"
    toggle.position = Vector2(100, 100)

    toggle.toggled.connect(func(is_on: bool):
        print("夜间模式：" + ("开" if is_on else "关"))
    )

    add_child(toggle)