Button

继承： BaseButton < Control < CanvasItem < Node < Object

派生： CheckBox, CheckButton, ColorPickerButton, MenuButton, OptionButton

按钮，支持主题，能够包含文本和图标。

描述

Button 是标准的主题按钮，可以包含文字和图标，显示样式会根据当前的 Theme 改变。

示例：通过代码创建按钮并指定在按下时的动作

GDScriptC#

func _ready():
    var button = Button.new()
    button.text = "Click me"
    button.pressed.connect(self._button_pressed)
    add_child(button)
func _button_pressed():
    print("Hello world!")

public override void _Ready()
{
    var button = new Button();
    button.Text = "Click me";
    button.Pressed += ButtonPressed;
    AddChild(button);
}
private void ButtonPressed()
{
    GD.Print("Hello world!");
}

另请参阅 BaseButton，其中包含与此节点相关联的通用属性和方法。

注意：按钮不处理触摸输入，因此不支持多点触控，因为模拟鼠标在给定时间只能按下一个按钮。请用 TouchScreenButton 制作触发游戏移动或动作的按钮。

教程

• 2D Dodge The Creeps 演示

• 操作系统测试演示

属性

主题属性

属性说明

HorizontalAlignment alignment = 1 🔗

• void set_text_alignment(value: HorizontalAlignment)

• HorizontalAlignment get_text_alignment()

按钮文本的文本对齐策略，使用 HorizontalAlignment 常量之一。

AutowrapMode autowrap_mode = 0 🔗

• void set_autowrap_mode(value: AutowrapMode)

• AutowrapMode get_autowrap_mode()

如果设置为 TextServer.AUTOWRAP_OFF 以外的值，则文本将在节点的边界矩形内换行。

bool clip_text = false 🔗

• void set_clip_text(value: bool)

• bool get_clip_text()

当此属性被启用时，过大而无法容纳按钮的文本会被剪掉，当被禁用时，按钮将始终有足够的宽度来容纳文本。

bool expand_icon = false 🔗

• void set_expand_icon(value: bool)

• bool is_expand_icon()

启用后，将在保持按钮图标长宽比的前提下对该图标进行扩展/收缩，从而适应按钮的大小。另见 icon_max_width。

bool flat = false 🔗

• void set_flat(value: bool)

• bool is_flat()

平面按钮不显示装饰。

Texture2D icon 🔗

• void set_button_icon(value: Texture2D)

• Texture2D get_button_icon()

按钮的图标，如果文本存在，则图标将被放置在文本之前。

要编辑图标的边距和间距，请使用 h_separation 主题属性，和所用 StyleBox 的 content_margin_* 属性。

HorizontalAlignment icon_alignment = 0 🔗

• void set_icon_alignment(value: HorizontalAlignment)

• HorizontalAlignment get_icon_alignment()

指定图标在按钮上水平对齐的方式应该为左对齐、右对齐还是居中对齐。请使用与文本对齐相同的 HorizontalAlignment 常量。如果水平居中并且垂直居中，则文本将被绘制在图标之上。

String language = "" 🔗

• void set_language(value: String)

• String get_language()

语言代码，用于断行和文本塑形算法，如果留空则使用当前区域设置。

String text = "" 🔗

• void set_text(value: String)

• String get_text()

该按钮的文本，将显示在按钮的区域内。

TextDirection text_direction = 0 🔗

• void set_text_direction(value: TextDirection)

• TextDirection get_text_direction()

基础文本书写方向。

OverrunBehavior text_overrun_behavior = 0 🔗

• void set_text_overrun_behavior(value: OverrunBehavior)

• OverrunBehavior get_text_overrun_behavior()

设置文本超出节点的边界矩形时的裁剪行为。有关所有模式的描述，请参阅 OverrunBehavior。

VerticalAlignment vertical_icon_alignment = 1 🔗

• void set_vertical_icon_alignment(value: VerticalAlignment)

• VerticalAlignment get_vertical_icon_alignment()

指定图标在按钮上垂直对齐的方式应该为顶端对齐、底部对齐还是居中对齐。请使用与文本对齐相同的 VerticalAlignment 常量。如果水平居中并且垂直居中，则文本将被绘制在图标之上。

主题属性说明

Color font_color = Color(0.875, 0.875, 0.875, 1) 🔗

该 Button 的默认文本 Color。

Color font_disabled_color = Color(0.875, 0.875, 0.875, 0.5) 🔗

该 Button 处于禁用状态时，使用的文本 Color。

Color font_focus_color = Color(0.95, 0.95, 0.95, 1) 🔗

该 Button 处于聚焦状态时，使用的文本 Color。只替换该按钮的正常文本颜色。禁用、悬停、按下状态优先于这个颜色。

Color font_hover_color = Color(0.95, 0.95, 0.95, 1) 🔗

该 Button 处于悬停状态时，使用的文本 Color。

Color font_hover_pressed_color = Color(1, 1, 1, 1) 🔗

该 Button 处于悬停并按下状态时，使用的文本 Color。

Color font_outline_color = Color(0, 0, 0, 1) 🔗

该 Button 的文本轮廓的色调。

Color font_pressed_color = Color(1, 1, 1, 1) 🔗

该 Button 处于按下状态时，使用的文本 Color 。

Color icon_disabled_color = Color(1, 1, 1, 0.4) 🔗

该 Button 处于禁用状态时，使用的图标调制 Color。

Color icon_focus_color = Color(1, 1, 1, 1) 🔗

该 Button 处于聚焦状态时，使用的图标调制 Color。仅替换该按钮的正常调制颜色。禁用、悬停和按下状态优先于这个颜色。

Color icon_hover_color = Color(1, 1, 1, 1) 🔗

该 Button 处于悬停状态时，使用的图标调制Color。

Color icon_hover_pressed_color = Color(1, 1, 1, 1) 🔗

该 Button 处于悬停并按下按下状态时，使用的图标调制 Color。

Color icon_normal_color = Color(1, 1, 1, 1) 🔗

该 Button 的默认图标调制 Color。

Color icon_pressed_color = Color(1, 1, 1, 1) 🔗

该 Button 处于按下状态时，使用的图标调制 Color。

int align_to_largest_stylebox = 0 🔗

This constant acts as a boolean. If true, the minimum size of the button and text/icon alignment is always based on the largest stylebox margins, otherwise it’s based on the current button state stylebox margins.

int h_separation = 4 🔗

Button 的图标和文本之间的水平间距。使用时会将负值当作 0。

int icon_max_width = 0 🔗

Button 图标的最大允许宽度。该限制应用于图标的默认大小，如果 expand_icon 为 true，则应用于其扩展大小。高度根据图标的缩放进行调整。如果按钮有其他图标（例如 CheckBox），它们也将会受到限制。

int outline_size = 0 🔗

文字轮廓的大小。

注意：如果使用启用了 FontFile.multichannel_signed_distance_field 的字体，其 FontFile.msdf_pixel_range 必须至少设置为 outline_size 的两倍，轮廓渲染才能看起来正确。否则，轮廓可能会比预期的更早被切断。

Font font 🔗

该 Button 文本的 Font。

int font_size 🔗

该 Button 文本的字体大小。

Texture2D icon 🔗

该 Button 的默认图标。仅在未指定 icon 时显示。

StyleBox disabled 🔗

该 Button 处于禁用状态时使用的 StyleBox。

StyleBox disabled_mirrored 🔗

该 Button 处于禁用状态时使用的 StyleBox（用于从右至左布局）。

StyleBox focus 🔗

该 Button 处于聚焦状态时使用的 StyleBox。focus StyleBox 显示在基础 StyleBox 之上，所以应该使用部分透明的 StyleBox，确保基础 StyleBox 仍然可见。代表轮廓或下划线的 StyleBox 可以很好地实现这个目的。要禁用聚焦的视觉效果，请指定 StyleBoxEmpty 资源。请注意，禁用聚焦的视觉效果会影响使用键盘/手柄进行导航的可用性，所以出于可访问性的原因，不建议这样做。

StyleBox hover 🔗

该 Button 处于悬停状态时使用的 StyleBox。

StyleBox hover_mirrored 🔗

该 Button 处于悬停状态时使用的 StyleBox（用于从右至左布局）。

StyleBox hover_pressed 🔗

该 Button 同时处于按下和悬停状态时使用的 StyleBox。

StyleBox hover_pressed_mirrored 🔗

该 Button 同时处于按下和悬停状态时使用的 StyleBox（用于从右至左布局）。

StyleBox normal 🔗

该 Button 的默认 StyleBox。

StyleBox normal_mirrored 🔗

该 Button 的默认 StyleBox（用于从右至左布局）。

StyleBox pressed 🔗

该 Button 处于按下状态时使用的 StyleBox。

StyleBox pressed_mirrored 🔗

该 Button 处于按下状态时使用的 StyleBox（用于从右至左布局）。