Up to date

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

TabBar

继承： Control < CanvasItem < Node < Object

提供水平选项卡栏的控件。

描述

提供水平选项卡栏的控件。类似于 TabContainer，但只负责绘制选项卡，不与子节点互动。

属性

bool

clip_tabs

true

int

current_tab

0

bool

drag_to_rearrange_enabled

false

FocusMode

focus_mode

2 (overrides Control)

int

max_tab_width

0

bool

scroll_to_selected

true

bool

scrolling_enabled

true

bool

select_with_rmb

false

AlignmentMode

tab_alignment

0

CloseButtonDisplayPolicy

tab_close_display_policy

0

int

tab_count

0

int

tabs_rearrange_group

-1

方法

void

add_tab ( String title="", Texture2D icon=null )

void

clear_tabs ( )

void

ensure_tab_visible ( int idx )

bool

get_offset_buttons_visible ( ) const

int

get_previous_tab ( ) const

Texture2D

get_tab_button_icon ( int tab_idx ) const

Texture2D

get_tab_icon ( int tab_idx ) const

int

get_tab_icon_max_width ( int tab_idx ) const

int

get_tab_idx_at_point ( Vector2 point ) const

String

get_tab_language ( int tab_idx ) const

Variant

get_tab_metadata ( int tab_idx ) const

int

get_tab_offset ( ) const

Rect2

get_tab_rect ( int tab_idx ) const

TextDirection

get_tab_text_direction ( int tab_idx ) const

String

get_tab_title ( int tab_idx ) const

bool

is_tab_disabled ( int tab_idx ) const

bool

is_tab_hidden ( int tab_idx ) const

void

move_tab ( int from, int to )

void

remove_tab ( int tab_idx )

bool

select_next_available ( )

bool

select_previous_available ( )

void

set_tab_button_icon ( int tab_idx, Texture2D icon )

void

set_tab_disabled ( int tab_idx, bool disabled )

void

set_tab_hidden ( int tab_idx, bool hidden )

void

set_tab_icon ( int tab_idx, Texture2D icon )

void

set_tab_icon_max_width ( int tab_idx, int width )

void

set_tab_language ( int tab_idx, String language )

void

set_tab_metadata ( int tab_idx, Variant metadata )

void

set_tab_text_direction ( int tab_idx, TextDirection direction )

void

set_tab_title ( int tab_idx, String title )

主题属性

Color

drop_mark_color

Color(1, 1, 1, 1)

Color

font_disabled_color

Color(0.875, 0.875, 0.875, 0.5)

Color

font_hovered_color

Color(0.95, 0.95, 0.95, 1)

Color

font_outline_color

Color(1, 1, 1, 1)

Color

font_selected_color

Color(0.95, 0.95, 0.95, 1)

Color

font_unselected_color

Color(0.7, 0.7, 0.7, 1)

int

h_separation

4

int

icon_max_width

0

int

outline_size

0

Font

font

int

font_size

Texture2D

close

Texture2D

decrement

Texture2D

decrement_highlight

Texture2D

drop_mark

Texture2D

increment

Texture2D

increment_highlight

StyleBox

button_highlight

StyleBox

button_pressed

StyleBox

tab_disabled

StyleBox

tab_focus

StyleBox

tab_hovered

StyleBox

tab_selected

StyleBox

tab_unselected

信号

active_tab_rearranged ( int idx_to )

通过鼠标拖动重新排列活动选项卡时发出。见 drag_to_rearrange_enabled。

tab_button_pressed ( int tab )

选项卡的右侧按钮被按下时发出。见 set_tab_button_icon。

tab_changed ( int tab )

切换到另一个选项卡时发出。

tab_clicked ( int tab )

单击选项卡时发出，即使它是当前选项卡。

tab_close_pressed ( int tab )

按下某个选项卡的关闭按钮时发出。

注意：按下关闭按钮后选项卡不会自动移除，这种行为需要手动实现。例如：

$TabBar.tab_close_pressed.connect($TabBar.remove_tab)

tab_hovered ( int tab )

当鼠标悬停选项卡时发出。

tab_rmb_clicked ( int tab )

右键单击选项卡时发出。必须启用 select_with_rmb。

tab_selected ( int tab )

通过点击、定向输入、或脚本选中某个选项卡时发出，即便该选项卡本来就是当前选项卡。

枚举

enum AlignmentMode:

AlignmentMode ALIGNMENT_LEFT = 0

将选项卡置于左侧。

AlignmentMode ALIGNMENT_CENTER = 1

将选项卡置于中间。

AlignmentMode ALIGNMENT_RIGHT = 2

将选项卡置于右侧。

AlignmentMode ALIGNMENT_MAX = 3

代表 AlignmentMode 枚举的大小。

enum CloseButtonDisplayPolicy:

CloseButtonDisplayPolicy CLOSE_BUTTON_SHOW_NEVER = 0

永远不会显示关闭按钮。

CloseButtonDisplayPolicy CLOSE_BUTTON_SHOW_ACTIVE_ONLY = 1

仅在当前活动选项卡上显示关闭按钮。

CloseButtonDisplayPolicy CLOSE_BUTTON_SHOW_ALWAYS = 2

在所有选项卡上显示关闭按钮。

CloseButtonDisplayPolicy CLOSE_BUTTON_MAX = 3

代表 CloseButtonDisplayPolicy 枚举的大小。

属性说明

bool clip_tabs = true

  • void set_clip_tabs ( bool value )

  • bool get_clip_tabs ( )

如果为 true，则会隐藏超出该节点宽度的选项卡，改为显示两个导航按钮。否则，会更新该节点的最小尺寸，让所有选项卡均可见。

int current_tab = 0

  • void set_current_tab ( int value )

  • int get_current_tab ( )

选择索引 tab_idx 处的选项卡。

bool drag_to_rearrange_enabled = false

  • void set_drag_to_rearrange_enabled ( bool value )

  • bool get_drag_to_rearrange_enabled ( )

如果为 true，可以通过鼠标拖动重新排列选项卡。

int max_tab_width = 0

  • void set_max_tab_width ( int value )

  • int get_max_tab_width ( )

设置所有选项卡应被限制的最大宽度。如果设置为 0，则无限制。

bool scroll_to_selected = true

  • void set_scroll_to_selected ( bool value )

  • bool get_scroll_to_selected ( )

如果为 true，则会更改选项卡偏移量，从而保持当前选中的选项卡可见。

bool scrolling_enabled = true

  • void set_scrolling_enabled ( bool value )

  • bool get_scrolling_enabled ( )

如果为 true，鼠标的滚轮可用于导航滚动视图。

bool select_with_rmb = false

  • void set_select_with_rmb ( bool value )

  • bool get_select_with_rmb ( )

如果为 true，启用鼠标右键选择选项卡。

AlignmentMode tab_alignment = 0

设置放置选项卡的位置。详情见 AlignmentMode。

CloseButtonDisplayPolicy tab_close_display_policy = 0

设置关闭按钮何时出现在选项卡上。有关详细信息，请参阅 CloseButtonDisplayPolicy。

int tab_count = 0

  • void set_tab_count ( int value )

  • int get_tab_count ( )

选项卡栏中当前的选项卡数量。

int tabs_rearrange_group = -1

  • void set_tabs_rearrange_group ( int value )

  • int get_tabs_rearrange_group ( )

具有相同重新排列组 ID 的 TabBar 将允许在它们之间拖动选项卡。使用 drag_to_rearrange_enabled 启用拖动。

将该属性设置为 -1 将禁用 TabBar 之间的重新排列。

方法说明

void add_tab ( String title="", Texture2D icon=null )

添加新选项卡。

void clear_tabs ( )

清空所有选项卡。

void ensure_tab_visible ( int idx )

移动滚动视图，使标签可见。

bool get_offset_buttons_visible ( ) const

如果偏移按钮（所有选项卡没有足够空间时出现的按钮）可见，则返回 true。

int get_previous_tab ( ) const

返回上一个活动选项卡的索引。

Texture2D get_tab_button_icon ( int tab_idx ) const

返回索引 tab_idx 处选项卡右侧按钮的图标，如果该按钮没有图标，则返回 null。

Texture2D get_tab_icon ( int tab_idx ) const

返回索引 tab_idx 处选项卡的图标，如果该选项卡没有图标，则返回 null。

int get_tab_icon_max_width ( int tab_idx ) const

设置索引为 tab_idx 处选项卡所允许的最大图标宽度。

int get_tab_idx_at_point ( Vector2 point ) const

返回位于局部坐标 point 处的选项卡的索引。如果该点在控件边界之外或查询位置没有选项卡，则返回 -1。

String get_tab_language ( int tab_idx ) const

返回选项卡标题的语言代码。

Variant get_tab_metadata ( int tab_idx ) const

返回索引为 tab_idx 的选项卡的元数据的值，由 set_tab_metadata 设置。如果之前没有设置元数据，则默认返回 null。

int get_tab_offset ( ) const

返回向左偏移的隐藏选项卡的数量。

Rect2 get_tab_rect ( int tab_idx ) const

返回带有局部位置和大小的选项卡 Rect2。

TextDirection get_tab_text_direction ( int tab_idx ) const

返回选项卡标题文本的基础书写方向。

String get_tab_title ( int tab_idx ) const

返回索引 tab_idx 处的选项卡的标题。

bool is_tab_disabled ( int tab_idx ) const

如果索引 tab_idx 处的选项卡被禁用，则返回 true。

bool is_tab_hidden ( int tab_idx ) const

如果索引 tab_idx 处的选项卡被隐藏，则返回 true。

void move_tab ( int from, int to )

将选项卡从 from 移动到 to。

void remove_tab ( int tab_idx )

删除索引 tab_idx 处的选项卡。

bool select_next_available ( )

选择索引大于当前所选选项卡索引的第一个可用选项卡。如果选项卡选择发生改变，则返回 true。

bool select_previous_available ( )

选择索引低于当前所选选项卡索引的第一个可用选项卡。如果选项卡选择发生改变，则返回 true。

void set_tab_button_icon ( int tab_idx, Texture2D icon )

设置索引为 tab_idx 的选项卡按钮的图标 icon（位于右侧，在关闭按钮之前），会将该按钮设为可见且可点击（见 tab_button_pressed）。给定 null 值会隐藏该按钮。

void set_tab_disabled ( int tab_idx, bool disabled )

如果 disabled 为 true，则禁用索引 tab_idx 处的选项卡，使其不可交互。

void set_tab_hidden ( int tab_idx, bool hidden )

如果 hidden 为 true，则隐藏索引 tab_idx 处的选项卡，使其从选项卡区域消失。

void set_tab_icon ( int tab_idx, Texture2D icon )

设置索引 tab_idx 处的选项卡的图标。

void set_tab_icon_max_width ( int tab_idx, int width )

设置索引为 tab_idx 处选项卡所允许的最大图标宽度。这是在图标的默认大小和 icon_max_width 的基础上的限制。高度会根据图标的长宽比调整。

void set_tab_language ( int tab_idx, String language )

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

void set_tab_metadata ( int tab_idx, Variant metadata )

为 tab_idx 的选项卡设置元数据的值，之后可以使用 get_tab_metadata 获取。

void set_tab_text_direction ( int tab_idx, TextDirection direction )

设置选项卡标题的基础书写方向。

void set_tab_title ( int tab_idx, String title )

设置索引 tab_idx 处的选项卡的标题 title。

主题属性说明

Color drop_mark_color = Color(1, 1, 1, 1)

drop_mark 图标的调制颜色。

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

禁用选项卡的字体颜色。

Color font_hovered_color = Color(0.95, 0.95, 0.95, 1)

当前悬停选项卡的字体颜色。不适用于选中的选项卡。

Color font_outline_color = Color(1, 1, 1, 1)

选项卡名称的文本轮廓的色调。

Color font_selected_color = Color(0.95, 0.95, 0.95, 1)

当前所选选项卡的字体颜色。

Color font_unselected_color = Color(0.7, 0.7, 0.7, 1)

其他未被选中的选项卡的字体颜色。

int h_separation = 4

选项卡内元素之间的水平分隔。

int icon_max_width = 0

选项卡图标所允许的最大宽度。这个限制应用在该图标默认大小之上，但是应用在 set_tab_icon_max_width 所设置的值之前。高度会根据图标比例调整。

int outline_size = 0

选项卡文字轮廓的大小。

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

Font font

用于绘制选项卡名称的字体。

int font_size

选项卡名称的字体大小。

Texture2D close

关闭按钮的图标（见 tab_close_display_policy）。

Texture2D decrement

左边的箭头按钮的图标，当有太多的标签无法容纳在容器的宽度内时出现。当该按钮被禁用时（即第一个标签是可见的），它显示为半透明的。

Texture2D decrement_highlight

当标签太多无法适应容器宽度时出现的左箭头按钮图标。当鼠标悬停在按钮上时使用。

Texture2D drop_mark

图标，用于指示拖动的选项卡将被放置到哪里（见 drag_to_rearrange_enabled）。

Texture2D increment

右箭头按钮的图标，当有太多的标签无法容纳在容器的宽度内时出现。当该按钮被禁用时（即最后一个标签是可见的），它显示为半透明的。

Texture2D increment_highlight

当标签太多无法适应容器宽度时出现的右箭头按钮图标。当鼠标悬停在按钮上时使用。

StyleBox button_highlight

选项卡和关闭按钮的背景，处于鼠标悬停状态时使用。

StyleBox button_pressed

选项卡和关闭按钮的背景，处于按下状态时使用。

StyleBox tab_disabled

选项卡处于禁用状态时的样式。

StyleBox tab_focus

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

StyleBox tab_hovered

当前悬停选项卡的样式。不适用于选择的选项卡。

注意：该样式将以至少与 tab_unselected 相同的宽度绘制。

StyleBox tab_selected

当前选中的选项卡的样式。

StyleBox tab_unselected

其他未被选中的选项卡的样式。