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

CheckBox

节点继承关系

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

定义

复选框就是那种前面有个小方框、可以勾选的控件。就像问卷调查里的"请勾选你感兴趣的项目"，可以同时勾多个。

使用频率：★★★ 一般常用（设置面板中常见）

节点用途

• 多选设置项（如同时开启音效和音乐）
• 权限确认（如"我已阅读并同意用户协议"）
• 功能开关（可以同时开启多个）

使用场景

• 游戏设置中的"启用音效"、"启用音乐"、"显示FPS"
• 注册/登录页面的"记住密码"、"自动登录"
• 许可协议的"我同意"勾选框

常用节点搭配

• 搭配 VBoxContainer 排列多个复选框
• 搭配 Label 显示说明文字

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

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

继承自 BaseButton

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

信号

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

常用方法

继承自 BaseButton 的所有方法。

代码示例

C

using Godot;

public partial class CheckBoxDemo : Control
{
    public override void _Ready()
    {
        var checkBox = new CheckBox();
        checkBox.Text = "启用音效";
        checkBox.Position = new Vector2(100, 100);

        // 监听勾选变化
        checkBox.Toggled += (isPressed) =>
        {
            GD.Print($"音效已{(isPressed ? "开启" : "关闭")}");
        };

        AddChild(checkBox);
    }
}

GDScript

extends Control

func _ready():
    var check_box = CheckBox.new()
    check_box.text = "启用音效"
    check_box.position = Vector2(100, 100)

    # 监听勾选变化
    check_box.toggled.connect(func(is_pressed: bool):
        print("音效已" + ("开启" if is_pressed else "关闭"))
    )

    add_child(check_box)