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

TextureButton

节点继承关系

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

定义

如果你觉得标准按钮太丑，想用自己画的图片做按钮——就用 TextureButton。它就像给按钮穿上了一件"自定义外衣"。这就像一件衣服有正、反两面，还有口袋——按钮的 4 种状态图就相当于"正常穿"、"趴下时"、"被人盯着看时"、"脱了"——每种情况展现不同的外观。

使用频率：★★★ 一般常用（需要自定义按钮外观时使用）

节点用途

• 用自定义图片作为按钮外观
• 制作图标式按钮（无文字，纯图片）
• 实现不同状态的视觉反馈（悬停、按下、禁用）

使用场景

• 游戏主菜单的精美图标按钮
• HUD 上的技能图标按钮
• 需要特殊视觉效果的功能按钮

常用节点搭配

• 搭配 CenterContainer 居中显示
• 搭配 HBoxContainer 排列多个图标按钮

生效必备素材/资源

• 正常状态图片（必需）
• 按下/悬停/禁用状态图片（推荐，提供完整视觉反馈）
• 图片格式：PNG（支持透明度）

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
texture_normal	Texture2D	null	—	正常状态下的图片
texture_pressed	Texture2D	null	—	按下时的图片
texture_hover	Texture2D	null	—	鼠标悬停时的图片
texture_disabled	Texture2D	null	—	禁用状态下的图片
texture_focused	Texture2D	null	—	获得键盘焦点时的图片
stretch_mode	枚举	Keep	—	图片拉伸方式
ignore_texture_size	bool	false	—	是否忽略图片原始尺寸

继承自 BaseButton

属性	类型	默认值	继承自	说明
disabled	bool	false	BaseButton	是否禁用
button_pressed	bool	false	BaseButton	是否处于按下状态
toggle_mode	bool	false	BaseButton	是否为切换模式

信号

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

常用方法

继承自 BaseButton 的所有方法。

代码示例

C

using Godot;

public partial class TextureButtonDemo : Control
{
    public override void _Ready()
    {
        var btn = new TextureButton();
        // 加载四种状态图（这里以路径示意，实际需要你有对应图片）
        btn.TextureNormal = GD.Load<Texture2D>("res://assets/btn_normal.png");
        btn.TexturePressed = GD.Load<Texture2D>("res://assets/btn_pressed.png");
        btn.TextureHover = GD.Load<Texture2D>("res://assets/btn_hover.png");
        btn.TextureDisabled = GD.Load<Texture2D>("res://assets/btn_disabled.png");
        btn.Position = new Vector2(100, 100);

        btn.Pressed += () => GD.Print("图片按钮被点击了！");

        AddChild(btn);
    }
}

GDScript

extends Control

func _ready():
    var btn = TextureButton.new()
    # 加载四种状态图（这里以路径示意，实际需要你有对应图片）
    btn.texture_normal = load("res://assets/btn_normal.png")
    btn.texture_pressed = load("res://assets/btn_pressed.png")
    btn.texture_hover = load("res://assets/btn_hover.png")
    btn.texture_disabled = load("res://assets/btn_disabled.png")
    btn.position = Vector2(100, 100)

    btn.pressed.connect(func(): print("图片按钮被点击了！"))

    add_child(btn)