Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

TabBar

继承： Control < CanvasItem < Node < Object

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

描述

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

属性

bool

clip_tabs

true

bool

close_with_middle_mouse

true

int

current_tab

-1

bool

deselect_enabled

false

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

bool

switch_on_drag_hover

true

AlignmentMode

tab_alignment

0

CloseButtonDisplayPolicy

tab_close_display_policy

0

int

tab_count

0

bool

tab_{index}/disabled

false

Texture2D

tab_{index}/icon

String

tab_{index}/title

""

String

tab_{index}/tooltip

""

int

tabs_rearrange_group

-1

方法

void

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

void

clear_tabs()

void

ensure_tab_visible(idx: int)

bool

get_offset_buttons_visible() const

int

get_previous_tab() const

Texture2D

get_tab_button_icon(tab_idx: int) const

Texture2D

get_tab_icon(tab_idx: int) const

int

get_tab_icon_max_width(tab_idx: int) const

int

get_tab_idx_at_point(point: Vector2) const

String

get_tab_language(tab_idx: int) const

Variant

get_tab_metadata(tab_idx: int) const

int

get_tab_offset() const

Rect2

get_tab_rect(tab_idx: int) const

TextDirection

get_tab_text_direction(tab_idx: int) const

String

get_tab_title(tab_idx: int) const

String

get_tab_tooltip(tab_idx: int) const

bool

is_tab_disabled(tab_idx: int) const

bool

is_tab_hidden(tab_idx: int) const

void

move_tab(from: int, to: int)

void

remove_tab(tab_idx: int)

bool

select_next_available()

bool

select_previous_available()

void

set_tab_button_icon(tab_idx: int, icon: Texture2D)

void

set_tab_disabled(tab_idx: int, disabled: bool)

void

set_tab_hidden(tab_idx: int, hidden: bool)

void

set_tab_icon(tab_idx: int, icon: Texture2D)

void

set_tab_icon_max_width(tab_idx: int, width: int)

void

set_tab_language(tab_idx: int, language: String)

void

set_tab_metadata(tab_idx: int, metadata: Variant)

void

set_tab_text_direction(tab_idx: int, direction: TextDirection)

void

set_tab_title(tab_idx: int, title: String)

void

set_tab_tooltip(tab_idx: int, tooltip: String)

主题属性

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(0, 0, 0, 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)

Color

icon_disabled_color

Color(1, 1, 1, 1)

Color

icon_hovered_color

Color(1, 1, 1, 1)

Color

icon_selected_color

Color(1, 1, 1, 1)

Color

icon_unselected_color

Color(1, 1, 1, 1)

int

h_separation

4

int

hover_switch_wait_msec

500

int

icon_max_width

0

int

outline_size

0

int

tab_separation

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(idx_to: int) 🔗

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

tab_button_pressed(tab: int) 🔗

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

tab_changed(tab: int) 🔗

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

tab_clicked(tab: int) 🔗

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

tab_close_pressed(tab: int) 🔗

当按下选项卡的关闭按钮时，或者如果 close_with_middle_mouse 为 true 且中键点击选项卡时，会发出。

注意：选项卡不会自动移除；这种行为需要手动编写代码来实现。例如：

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

tab_hovered(tab: int) 🔗

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

tab_rmb_clicked(tab: int) 🔗

右键点击选项卡时发出。

tab_selected(tab: int) 🔗

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

枚举

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(value: bool)

  • bool get_clip_tabs()

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

bool close_with_middle_mouse = true 🔗

  • void set_close_with_middle_mouse(value: bool)

  • bool get_close_with_middle_mouse()

如果为 true，则在选项卡上点击鼠标中键将发出 tab_close_pressed 信号。

int current_tab = -1 🔗

  • void set_current_tab(value: int)

  • int get_current_tab()

当前选中选项卡的索引号。-1 表示没有选中任何选项卡，只有在 deselect_enabled 为 true 或所有选项卡都处于隐藏或禁用状态下才能够设置。

bool deselect_enabled = false 🔗

  • void set_deselect_enabled(value: bool)

  • bool get_deselect_enabled()

如果为 true，则所有选项卡都可以被取消选择，不选中任何选项卡。单击当前选项卡取消选中。

bool drag_to_rearrange_enabled = false 🔗

  • void set_drag_to_rearrange_enabled(value: bool)

  • bool get_drag_to_rearrange_enabled()

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

int max_tab_width = 0 🔗

  • void set_max_tab_width(value: int)

  • int get_max_tab_width()

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

bool scroll_to_selected = true 🔗

  • void set_scroll_to_selected(value: bool)

  • bool get_scroll_to_selected()

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

bool scrolling_enabled = true 🔗

  • void set_scrolling_enabled(value: bool)

  • bool get_scrolling_enabled()

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

bool select_with_rmb = false 🔗

  • void set_select_with_rmb(value: bool)

  • bool get_select_with_rmb()

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

bool switch_on_drag_hover = true 🔗

  • void set_switch_on_drag_hover(value: bool)

  • bool get_switch_on_drag_hover()

如果为 true，则在拖动内容时将鼠标悬停在选项卡上将切换到该选项卡。将鼠标悬停在另一个标签页上进行重新排列时无效。该操作的延迟时间由 hover_switch_wait_msec 决定。

AlignmentMode tab_alignment = 0 🔗

选项卡的水平对齐方式。

CloseButtonDisplayPolicy tab_close_display_policy = 0 🔗

选项卡上显示关闭按钮的时机。

int tab_count = 0 🔗

  • void set_tab_count(value: int)

  • int get_tab_count()

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

bool tab_{index}/disabled = false 🔗

如果为 true，则 index 处的选项卡将被禁用。

注意： index 的取值范围为 0 .. tab_count - 1。

Texture2D tab_{index}/icon 🔗

如果为 true，则 index 处的选项卡将被隐藏。

注意： index 的取值范围为 0 .. tab_count - 1。

String tab_{index}/title = "" 🔗

index处选项卡的标题文本。

注意： index 的取值范围为 0 .. tab_count - 1。

String tab_{index}/tooltip = "" 🔗

index 处选项卡的工具提示文本。

注意： index 的取值范围为 0 .. tab_count - 1。

int tabs_rearrange_group = -1 🔗

  • void set_tabs_rearrange_group(value: int)

  • int get_tabs_rearrange_group()

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

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

方法说明

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

添加新选项卡。

void clear_tabs() 🔗

清空所有选项卡。

void ensure_tab_visible(idx: int) 🔗

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

bool get_offset_buttons_visible() const 🔗

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

int get_previous_tab() const 🔗

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

Texture2D get_tab_button_icon(tab_idx: int) const 🔗

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

Texture2D get_tab_icon(tab_idx: int) const 🔗

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

int get_tab_icon_max_width(tab_idx: int) const 🔗

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

int get_tab_idx_at_point(point: Vector2) const 🔗

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

String get_tab_language(tab_idx: int) const 🔗

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

Variant get_tab_metadata(tab_idx: int) const 🔗

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

int get_tab_offset() const 🔗

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

Rect2 get_tab_rect(tab_idx: int) const 🔗

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

TextDirection get_tab_text_direction(tab_idx: int) const 🔗

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

String get_tab_title(tab_idx: int) const 🔗

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

String get_tab_tooltip(tab_idx: int) const 🔗

返回索引 tab_idx 处的选项卡的工具提示文本。

bool is_tab_disabled(tab_idx: int) const 🔗

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

bool is_tab_hidden(tab_idx: int) const 🔗

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

void move_tab(from: int, to: int) 🔗

将选项卡从 from 移动到 to。

void remove_tab(tab_idx: int) 🔗

删除索引 tab_idx 处的选项卡。

bool select_next_available() 🔗

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

bool select_previous_available() 🔗

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

void set_tab_button_icon(tab_idx: int, icon: Texture2D) 🔗

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

void set_tab_disabled(tab_idx: int, disabled: bool) 🔗

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

void set_tab_hidden(tab_idx: int, hidden: bool) 🔗

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

void set_tab_icon(tab_idx: int, icon: Texture2D) 🔗

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

void set_tab_icon_max_width(tab_idx: int, width: int) 🔗

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

void set_tab_language(tab_idx: int, language: String) 🔗

将索引为 tab_idx 的选项卡的标题语言代码设置为 language。这是用于断行和文本塑形算法的。如果 language 为空，则使用当前区域设置。

void set_tab_metadata(tab_idx: int, metadata: Variant) 🔗

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

void set_tab_text_direction(tab_idx: int, direction: TextDirection) 🔗

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

void set_tab_title(tab_idx: int, title: String) 🔗

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

void set_tab_tooltip(tab_idx: int, tooltip: String) 🔗

设置索引 tab_idx 处的选项卡的工具提示 tooltip。

注意：默认情况下，如果 tooltip 为空而选项卡文本发生了裁剪（选项卡无法完整显示所有字符），那么就会将标题作为工具提示显示。要隐藏工具提示，请将 tooltip 文本设置为 " "。

主题属性说明

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(0, 0, 0, 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) 🔗

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

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

禁用的选项卡的图标颜色。

Color icon_hovered_color = Color(1, 1, 1, 1) 🔗

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

Color icon_selected_color = Color(1, 1, 1, 1) 🔗

当前所选选项卡的图标颜色。

Color icon_unselected_color = Color(1, 1, 1, 1) 🔗

其他未被选中的选项卡的图标颜色。

int h_separation = 4 🔗

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

int hover_switch_wait_msec = 500 🔗

在拖放操作中，切换选项卡之前需要等待的毫秒数。

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 的两倍，轮廓渲染才能看起来正确。否则，轮廓可能会比预期的更早被切断。

int tab_separation = 0 🔗

选项卡栏中选项卡的间距。

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 🔗

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