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

TouchScreenButton

节点继承关系

继承链：Node -> Node2D -> TouchScreenButton

Node

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

定义

TouchScreenButton 是专门为手机/平板触摸屏设计的虚拟按钮。和普通的 Button 不同，它是一个2D节点（继承自 Node2D），可以直接放在游戏画面中。玩家用手指点击/触摸它就能触发事件。

简单说：手机游戏屏幕上的虚拟按钮，比如摇杆、攻击键、跳跃键。

使用频率：★ 基本用不到

节点用途

• 虚拟摇杆区域：标记摇杆的触摸区域
• 动作按钮：攻击、跳跃、技能等虚拟按钮
• 菜单按钮：暂停、背包、设置等
• 手机端适配：将键盘操作映射到触摸按钮

使用场景

场景	说明
手机动作游戏	屏幕左下角放虚拟摇杆，右下角放攻击和跳跃按钮
手机射击游戏	屏幕右侧放射击按钮和瞄准按钮
手机策略游戏	放置各种功能按钮

常用节点搭配

搭配节点	搭配方式
TextureRect / Sprite2D	作为子节点显示按钮外观
CanvasLayer	放在 CanvasLayer 中确保按钮永远在最前面

生效必备素材/资源

TouchScreenButton 需要设置 texture_normal（正常状态图片）和可选的 texture_pressed（按下状态图片）。

节点属性与信号

属性

属性	类型	默认值	继承自	说明
texture_normal	Texture2D	null	TouchScreenButton	正常状态的按钮图片
texture_pressed	Texture2D	null	TouchScreenButton	按下状态的按钮图片
texture_disabled	Texture2D	null	TouchScreenButton	禁用状态的按钮图片
shape	Shape2D	null	TouchScreenButton	触摸检测区域形状（默认用图片大小）
action	string	""	TouchScreenButton	绑定的输入动作名称，按下时自动触发该动作
visibility_mode	int	0	TouchScreenButton	可见性模式：0=总是可见，1=仅触摸时可见
passby_press	bool	false	TouchScreenButton	手指滑过时是否触发（false=必须精确点按）

信号

信号	参数	说明
pressed	无	按下时触发
released	无	松开时触发

常用方法

方法	返回值	说明
IsPressed()	bool	当前是否被按下

代码示例

C

// C# - 虚拟跳跃按钮
using Godot;

public partial class TouchJumpButton : TouchScreenButton
{
    [Export] public string ExJumpAction = "jump";

    public override void _Ready()
    {
        // 将触摸按钮绑定到输入动作
        Action = ExJumpAction;
        Pressed += OnButtonPressed;
        Released += OnButtonReleased;
    }

    private void OnButtonPressed()
    {
        GD.Print("跳跃按钮按下");
    }

    private void OnButtonReleased()
    {
        GD.Print("跳跃按钮松开");
    }
}

GDScript

# GDScript - 虚拟跳跃按钮
extends TouchScreenButton

@export var jump_action: String = "jump"

func _ready():
    # 将触摸按钮绑定到输入动作
    action = jump_action
    pressed.connect(_on_button_pressed)
    released.connect(_on_button_released)

func _on_button_pressed():
    print("跳跃按钮按下")

func _on_button_released():
    print("跳跃按钮松开")