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

Button

节点继承关系

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

定义

标准按钮——你在所有软件、网页、游戏里都见过的那种"可以点击的方块"。上面写文字，点一下就执行某个操作。就像遥控器上的按键，按一下就触发一个动作。

使用频率：★★★★ 维度专用常用（几乎每个 UI 都会用到按钮）

节点用途

• 触发游戏操作（开始、暂停、退出）
• 确认/取消操作
• 导航跳转

使用场景

• 主菜单的"开始游戏"、"设置"、"退出"按钮
• 游戏内 HUD 的"攻击"、"防御"按钮
• 对话框的"确定"、"取消"按钮

常用节点搭配

• 搭配 HBoxContainer / VBoxContainer 排列多个按钮
• 搭配 PanelContainer 做带背景的按钮组

生效必备素材/资源

无需特殊资源。可选：图标图片（Texture2D）用于在按钮上显示小图标。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
text	string	""	—	按钮上显示的文字
icon	Texture2D	null	—	按钮上显示的小图标
flat	bool	false	—	是否为扁平样式（无背景）
clip_text	bool	false	—	文字超出按钮宽度时是否裁剪
text_overrun_behavior	枚举	Ellipsis	—	文字溢出时的处理方式

继承自 BaseButton

属性	类型	默认值	继承自	说明
disabled	bool	false	BaseButton	是否禁用（变灰，不可点击）
button_pressed	bool	false	BaseButton	按钮是否处于按下状态
toggle_mode	bool	false	BaseButton	是否为切换模式（点一下开、再点一下关）
action_mode	枚举	Press	BaseButton	按钮响应模式
button_group	ButtonGroup	null	BaseButton	按钮组（用于单选互斥）

信号

信号	触发时机	参数
pressed	按钮被点击（按下并松开）时	无
button_down	鼠标按下时（还没松开）	无
button_up	鼠标松开时	无
toggled	切换状态变化时（需开启 toggle_mode）	bool 是否按下

常用方法

方法	说明
SetDisabled(bool)	设置是否禁用
SetPressed(bool)	设置按下状态
SetToggleMode(bool)	设置是否为切换模式

代码示例

C

using Godot;

public partial class ButtonDemo : Control
{
    public override void _Ready()
    {
        var button = new Button();
        button.Text = "点击我";
        button.Position = new Vector2(100, 100);
        button.Size = new Vector2(150, 40);

        // 连接点击信号
        button.Pressed += OnButtonPressed;

        AddChild(button);
    }

    private void OnButtonPressed()
    {
        GD.Print("按钮被点击了！");
    }
}

GDScript

extends Control

func _ready():
    var button = Button.new()
    button.text = "点击我"
    button.position = Vector2(100, 100)
    button.size = Vector2(150, 40)

    # 连接点击信号
    button.pressed.connect(_on_button_pressed)

    add_child(button)

func _on_button_pressed():
    print("按钮被点击了！")