Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Button

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

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

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

描述

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

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

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!")

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

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

教程

属性

HorizontalAlignment

alignment

1

bool

clip_text

false

bool

expand_icon

false

bool

flat

false

Texture2D

icon

HorizontalAlignment

icon_alignment

0

String

language

""

String

text

""

TextDirection

text_direction

0

OverrunBehavior

text_overrun_behavior

0

VerticalAlignment

vertical_icon_alignment

1

主题属性

Color

font_color

Color(0.875, 0.875, 0.875, 1)

Color

font_disabled_color

Color(0.875, 0.875, 0.875, 0.5)

Color

font_focus_color

Color(0.95, 0.95, 0.95, 1)

Color

font_hover_color

Color(0.95, 0.95, 0.95, 1)

Color

font_hover_pressed_color

Color(1, 1, 1, 1)

Color

font_outline_color

Color(1, 1, 1, 1)

Color

font_pressed_color

Color(1, 1, 1, 1)

Color

icon_disabled_color

Color(1, 1, 1, 0.4)

Color

icon_focus_color

Color(1, 1, 1, 1)

Color

icon_hover_color

Color(1, 1, 1, 1)

Color

icon_hover_pressed_color

Color(1, 1, 1, 1)

Color

icon_normal_color

Color(1, 1, 1, 1)

Color

icon_pressed_color

Color(1, 1, 1, 1)

int

h_separation

4

int

icon_max_width

0

int

outline_size

0

Font

font

int

font_size

Texture2D

icon

StyleBox

disabled

StyleBox

disabled_mirrored

StyleBox

focus

StyleBox

hover

StyleBox

hover_mirrored

StyleBox

hover_pressed

StyleBox

hover_pressed_mirrored

StyleBox

normal

StyleBox

normal_mirrored

StyleBox

pressed

StyleBox

pressed_mirrored


属性说明

HorizontalAlignment alignment = 1

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


bool clip_text = false

  • void set_clip_text ( bool value )

  • bool get_clip_text ( )

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


bool expand_icon = false

  • void set_expand_icon ( bool value )

  • bool is_expand_icon ( )

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


bool flat = false

  • void set_flat ( bool value )

  • bool is_flat ( )

平面按钮不显示装饰。


Texture2D icon

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

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


HorizontalAlignment icon_alignment = 0

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


String language = ""

  • void set_language ( String value )

  • String get_language ( )

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


String text = ""

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


TextDirection text_direction = 0

基础文本书写方向。


OverrunBehavior text_overrun_behavior = 0

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


VerticalAlignment vertical_icon_alignment = 1

指定图标在按钮上垂直对齐的方式应该为顶端对齐、底部对齐还是居中对齐。请使用与文本对齐相同的 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(1, 1, 1, 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 h_separation = 4

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


int icon_max_width = 0

Button 图标的最大允许宽度。如果 expand_icontrue,则该限制适用于图标的默认大小或扩展大小。高度将根据图标的比例进行调整。


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 处于聚焦状态时使用的 StyleBoxfocus 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(用于从右至左布局)。