Control

继承： CanvasItem < Node < Object

派生： BaseButton, ColorRect, Container, GraphEdit, ItemList, Label, LineEdit, MenuBar, NinePatchRect, Panel, Range, ReferenceRect, RichTextLabel, Separator, TabBar, TextEdit, TextureRect, Tree, VideoStreamPlayer

所有 GUI 控件的基类。根据其父控件调整其位置和大小。

描述

所有 UI 相关节点的基类。Control 具有定义其范围的边界矩形，相对于父控件或当前视口的锚点位置，以及相对于锚点的偏移。当节点、任何父节点或屏幕尺寸发生变化时，偏移就会自动更新。

更多关于 Godot 的 UI 系统、锚点、偏移和容器的信息，请参阅手册中的相关教程。要构建灵活的 UI，你需要混合使用从 Control 和 Container 节点继承的 UI 元素。

用户界面节点与输入

Godot 使用视口来传播输入事件。视口负责将 InputEvent 传播给它的子节点。因为 SceneTree.root 是 Window，所以游戏中的所有 UI 元素都会自动进行传播。

输入事件通过调用 Node._input 在 SceneTree 中传播，从根节点传播到所有子节点。对 UI 元素而言，覆盖的最好是 _gui_input，可以过滤掉无关的输入事件，例如它会对 Z 顺序、mouse_filter、焦点、事件是否在该控件的边界框内等条件进行检查。

请调用 accept_event，这样其他节点就不会收到该事件。输入被接受后，就会被标记为已处理，Node._unhandled_input 不会对它进行处理。

只能有一个 Control 节点处于焦点。只有处于焦点的节点才会接收到事件。要获得焦点，请调用 grab_focus。导致 Control 节点失去焦点的情况有：其他节点获得了焦点、隐藏了聚焦节点。

将 mouse_filter 设置为 MOUSE_FILTER_IGNORE 可以让 Control 节点忽略鼠标或触摸事件。如果你在按钮上放了一个图标，就会需要用到。

Theme 资源会更改控件的外观。如果你更改了 Control 节点上的 Theme，则会影响其所有子节点。要覆盖某些主题的参数，请调用 add_theme_*_override 方法，例如 add_theme_font_override。你可以使用检查器覆盖主题。

注意：主题项不是 Object 的属性。这意味着你无法使用 Object.get 和 Object.set 访问它们的值。请改用这个类的 get_theme_* 和 add_theme_*_override 方法。

教程

• GUI 文档索引

• 2D 中的自定义绘图

• 控件节点一览

• 多分辨率

• 所有 GUI 演示

属性

方法

信号

focus_entered() 🔗

当该节点获得焦点时发出。

focus_exited() 🔗

当该节点失去焦点时发出。

gui_input(event: InputEvent) 🔗

当节点收到 InputEvent 时发出。

minimum_size_changed() 🔗

当节点的最小大小更改时发出。

mouse_entered() 🔗

当鼠标光标进入控件（或任何子控件）的可见区域时发出，可见区域即未被其他 Control 和 Window 遮挡的区域，需要 mouse_filter 允许事件达到，与控件是否持有焦点无关。

注意：CanvasItem.z_index 不影响哪个 Control 会收到信号。

mouse_exited() 🔗

当鼠标光标离开控件（或任何子控件）的可见区域时发出，可见区域即未被其他 Control 和 Window 遮挡的区域，需要 mouse_filter 允许事件达到，与控件是否持有焦点无关。

注意：CanvasItem.z_index 不影响哪个 Control 会收到信号。

注意：如果要忽略任何顶部节点，检查鼠标是否真的离开了该区域，可以使用如下代码：

func _on_mouse_exited():
    if not Rect2(Vector2(), size).has_point(get_local_mouse_position()):
        # 未悬停在区域上。

resized() 🔗

当控件更改大小时发出。

size_flags_changed() 🔗

当大小标志之一更改时发出。见 size_flags_horizontal 和 size_flags_vertical。

theme_changed() 🔗

发送 NOTIFICATION_THEME_CHANGED 通知时发出。

枚举

enum FocusMode: 🔗

FocusMode FOCUS_NONE = 0

该节点无法获取焦点。在 focus_mode 中使用。

FocusMode FOCUS_CLICK = 1

该节点只能通过鼠标点击获取焦点。在 focus_mode 中使用。

FocusMode FOCUS_ALL = 2

该节点可以通过鼠标单击、使用键盘上的箭头和 Tab 键或使用游戏手柄上的方向键来获取焦点。用于 focus_mode。

enum CursorShape: 🔗

CursorShape CURSOR_ARROW = 0

当用户将节点悬停时，显示系统的箭头鼠标光标。与 mouse_default_cursor_shape 成员一起使用。

CursorShape CURSOR_IBEAM = 1

当用户将节点悬停时，显示系统的 I 型光束鼠标光标。工字梁指针的形状类似于“I”。它告诉用户他们可以突出显示或插入文本。

CursorShape CURSOR_POINTING_HAND = 2

当用户将节点悬停时，显示系统的手形鼠标光标。

CursorShape CURSOR_CROSS = 3

当用户将鼠标悬停在节点上时，显示系统的交叉鼠标光标。

CursorShape CURSOR_WAIT = 4

当用户悬停节点时，显示系统等待的鼠标光标。通常是一个沙漏。

CursorShape CURSOR_BUSY = 5

当用户悬停节点时，显示系统繁忙的鼠标光标。通常是箭头加一个小沙漏。

CursorShape CURSOR_DRAG = 6

当用户悬停在节点上时，显示系统的拖动鼠标光标，通常是一个闭合的拳头或十字符号。它告诉用户他们当前正在拖动一个项目，例如场景面板中的节点。

CursorShape CURSOR_CAN_DROP = 7

当用户悬停节点时，显示系统的落地鼠标光标。它可以是一个张开的手。它告诉用户可以放下一个他们当前正在抓取的物品，比如场景面板中的一个节点。

CursorShape CURSOR_FORBIDDEN = 8

当用户悬停节点时，显示系统禁止的鼠标光标。通常是一个交叉的圆圈。

CursorShape CURSOR_VSIZE = 9

当用户悬停节点时，显示系统的垂直调整鼠标光标。一个双头的垂直箭头。它告诉用户可以垂直调整窗口或面板的大小。

CursorShape CURSOR_HSIZE = 10

当用户悬停节点时，显示系统的水平调整鼠标光标。一个双头的水平箭头。它告诉用户可以水平调整窗口或面板的大小。

CursorShape CURSOR_BDIAGSIZE = 11

当用户将节点悬停时，显示系统窗口调整大小的鼠标光标。光标是从左下角到右上角的双向箭头。它告诉用户可以水平和垂直调整窗口或面板的大小。

CursorShape CURSOR_FDIAGSIZE = 12

当用户将节点悬停时，显示系统窗口调整大小的鼠标光标。光标是一个双向箭头，从左上角到右下角，与 CURSOR_BDIAGSIZE 相反。它告诉用户可以水平和垂直调整窗口或面板的大小。

CursorShape CURSOR_MOVE = 13

当用户将节点悬停时，显示系统的移动鼠标光标。它以 90 度角显示 2 个双向箭头。它告诉用户他们可以自由移动 UI 元素。

CursorShape CURSOR_VSPLIT = 14

当用户将节点悬停时，显示系统的垂直拆分鼠标光标。在 Windows 上与 CURSOR_VSIZE 相同。

CursorShape CURSOR_HSPLIT = 15

当用户将节点悬停时，显示系统的水平拆分鼠标光标。在 Windows 上与 CURSOR_HSIZE 相同。

CursorShape CURSOR_HELP = 16

当用户将节点悬停在一个节点上时，显示系统的帮助鼠标光标，一个问号。

enum LayoutPreset: 🔗

LayoutPreset PRESET_TOP_LEFT = 0

将所有 4 个锚点对齐到父控件边界的左上角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_TOP_RIGHT = 1

将所有 4 个锚点对齐到父控件边界的右上角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_BOTTOM_LEFT = 2

将所有 4 个锚点对齐到父控件边界的左下角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_BOTTOM_RIGHT = 3

将所有 4 个锚点对齐到父控件边界的右下角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_CENTER_LEFT = 4

将所有 4 个锚点对齐到父控件边界的左边缘的中点。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_CENTER_TOP = 5

将所有 4 个锚点对齐到父控件边界的顶边缘的中点。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_CENTER_RIGHT = 6

将所有 4 个锚点对齐到父控件边界的右边缘的中点。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_CENTER_BOTTOM = 7

将所有 4 个锚点对齐到父控件边界的底边缘的中点。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_CENTER = 8

将所有 4 个锚点对齐到父控件边界的中心。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_LEFT_WIDE = 9

将所有 4 个锚点对齐到父控件的左边缘。左偏移量相对于父节点的左边缘，上偏移量相对于父节点的左上角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_TOP_WIDE = 10

将所有 4 个锚点对齐到父控件的上边缘。左偏移量相对于父节点的左上角，上偏移量相对于父节点的上边缘，右偏移相对于父节点的右上角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_RIGHT_WIDE = 11

将所有 4 个锚点对齐到父控件的右边缘。右偏移量相对于父节点的右边缘，上偏移量相对于父节点的右上角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_BOTTOM_WIDE = 12

将所有 4 个锚点对齐到父控件的下边缘。左偏移量相对于父节点的左下角，下偏移量相对于父节点的下边缘，右偏移相对于父节点的右下角。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_VCENTER_WIDE = 13

将所有 4 个锚点对齐到一条垂直线，该垂直线将父控件切成两半。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_HCENTER_WIDE = 14

将所有 4 个锚点对齐到一条水平线，该水平线将父控件切成两半。与 set_anchors_preset 一起使用。

LayoutPreset PRESET_FULL_RECT = 15

将所有 4 个锚点对齐到父控件对应的角。应用此预设后，会将所有 4 个偏移都设置为 0，该 Control 将适合其父控件。与 set_anchors_preset 一起使用。

enum LayoutPresetMode: 🔗

LayoutPresetMode PRESET_MODE_MINSIZE = 0

控件将被调整为最小尺寸。

LayoutPresetMode PRESET_MODE_KEEP_WIDTH = 1

控件的宽度不会改变。

LayoutPresetMode PRESET_MODE_KEEP_HEIGHT = 2

控件的高度不会改变。

LayoutPresetMode PRESET_MODE_KEEP_SIZE = 3

控件的大小不会改变。

flags SizeFlags: 🔗

SizeFlags SIZE_SHRINK_BEGIN = 0

告诉父级 Container 将该节点与其起点对齐，即顶部或左侧。它与 SIZE_FILL 以及其他收缩大小标志互斥，但可以在某些容器中与 SIZE_EXPAND 一起使用。与 size_flags_horizontal 和 size_flags_vertical 一起使用。

注意：设置这个标志相当于没有任何大小标志。

SizeFlags SIZE_FILL = 1

告诉父级 Container 扩展该节点的边界以填充所有可用空间，而无需推动任何其他节点。它与收缩大小标志互斥。与 size_flags_horizontal 和 size_flags_vertical 一起使用。

SizeFlags SIZE_EXPAND = 2

告诉父级 Container 让该节点占用你标记的轴上的所有可用空间。如果将多个相邻节点设置为扩展，它们将根据其拉伸比共享空间。见 size_flags_stretch_ratio。用于 size_flags_horizontal 和 size_flags_vertical。

SizeFlags SIZE_EXPAND_FILL = 3

将该节点的大小标志设置为填充和扩展。有关详细信息，请参阅 SIZE_FILL 和 SIZE_EXPAND。

SizeFlags SIZE_SHRINK_CENTER = 4

告诉父级 Container 将节点置于可用空间的中心。它与 SIZE_FILL 以及其他收缩大小标志互斥，但可以在某些容器中与 SIZE_EXPAND 一起使用。与 size_flags_horizontal 和 size_flags_vertical 一起使用。

SizeFlags SIZE_SHRINK_END = 8

告诉父级 Container 将节点与其末端对齐，即底部或右侧。它与 SIZE_FILL 以及其他收缩大小标志互斥，但可以在某些容器中与 SIZE_EXPAND 一起使用。与 size_flags_horizontal 和 size_flags_vertical 一起使用。

enum MouseFilter: 🔗

MouseFilter MOUSE_FILTER_STOP = 0

在控件上点击时，将通过 _gui_input 收到鼠标移动输入事件和鼠标按钮输入事件。控件能够接收到 mouse_entered 和 mouse_exited 信号。这些事件将自动被标记为已处理，不会进一步传播到其他控件。这也会导致其他控件中的信号被阻止。

MouseFilter MOUSE_FILTER_PASS = 1

在控件上点击时，将通过 _gui_input 收到鼠标移动输入事件和鼠标按钮输入事件。并且控件能够接收到 mouse_entered 和 mouse_exited 信号。如果此控件不处理事件，则将考虑其父控件（如果有的话），依此类推，直到没有更多的父控件可以处理该事件。这也允许信号在其他控件中触发。如果没有控件处理它，该事件将被传递到 Node._shortcut_input 进行进一步处理。

MouseFilter MOUSE_FILTER_IGNORE = 2

在控件上点击时，不会通过 _gui_input 收到鼠标移动输入事件和鼠标按钮输入事件，也不会接收到 mouse_entered 和 mouse_exited 信号。这不会阻止其他控件接收这些事件或触发信号。被忽略的事件将不会被自动处理。

注意：如果控件已收到 mouse_entered 但未收到 mouse_exited，则将 mouse_filter 更改为 MOUSE_FILTER_IGNORE 将导致发出 mouse_exited。

enum GrowDirection: 🔗

GrowDirection GROW_DIRECTION_BEGIN = 0

如果控件的最小尺寸更改为大于其相应轴上的当前尺寸，则控件将向左或顶部增大以进行组合。

GrowDirection GROW_DIRECTION_END = 1

如果控件的最小尺寸更改为大于其相应轴上的当前尺寸，则控件将向右或向下增大以进行补偿。

GrowDirection GROW_DIRECTION_BOTH = 2

如果控件的最小大小更改为大于其当前大小，则控件将在两个方向上均等地增长以组成该控件。

enum Anchor: 🔗

Anchor ANCHOR_BEGIN = 0

将 4 个锚点的某一侧吸附到节点的 Rect 的左上角。在 anchor_* 成员变量中使用，例如 anchor_left。要一次更改全部 4 个锚点，请使用 set_anchors_preset。

Anchor ANCHOR_END = 1

将 4 个锚点的某一侧吸附到节点的 Rect 的右下角。在 anchor_* 成员变量中使用，例如 anchor_left。要一次更改全部 4 个锚点，请使用 set_anchors_preset。

enum LayoutDirection: 🔗

LayoutDirection LAYOUT_DIRECTION_INHERITED = 0

自动布局方向，由父控件布局方向决定。

LayoutDirection LAYOUT_DIRECTION_LOCALE = 1

自动布局方向，根据当前语言环境确定。

LayoutDirection LAYOUT_DIRECTION_LTR = 2

从左至右的布局方向。

LayoutDirection LAYOUT_DIRECTION_RTL = 3

从右至左的布局方向。

enum TextDirection: 🔗

TextDirection TEXT_DIRECTION_INHERITED = 3

文字书写方向与布局方向相同。

TextDirection TEXT_DIRECTION_AUTO = 0

自动文本书写方向，根据当前区域设置和文本内容确定。

TextDirection TEXT_DIRECTION_LTR = 1

从左至右的文本书写方向。

TextDirection TEXT_DIRECTION_RTL = 2

从右至左的文本书写方向。

常量

NOTIFICATION_RESIZED = 40 🔗

当节点改变大小时发送。请使用 size 获取新大小。

NOTIFICATION_MOUSE_ENTER = 41 🔗

当鼠标光标进入控件（或任何子控件）的可见区域时发送，可见区域即未被其他 Control 和 Window 遮挡的区域，需要 mouse_filter 允许事件达到，与控件是否持有焦点无关。

注意：CanvasItem.z_index 不影响哪个 Control 会收到该通知。

另见 NOTIFICATION_MOUSE_ENTER_SELF。

NOTIFICATION_MOUSE_EXIT = 42 🔗

当鼠标光标离开控件（以及所有子控件）的可见区域时发送，可见区域即未被其他 Control 和 Window 遮挡的区域，需要 mouse_filter 允许事件达到，与控件是否持有焦点无关。

注意：CanvasItem.z_index 不影响哪个 Control 会收到该通知。

另见 NOTIFICATION_MOUSE_EXIT_SELF。

NOTIFICATION_MOUSE_ENTER_SELF = 60 🔗

实验性： The reason this notification is sent may change in the future.

当鼠标光标进入控件的可见区域时发送，可见区域即未被其他 Control 和 Window 遮挡的区域，需要 mouse_filter 允许事件达到，与控件是否持有焦点无关。

注意：CanvasItem.z_index 不影响哪个 Control 会收到该通知。

另见 NOTIFICATION_MOUSE_ENTER。

NOTIFICATION_MOUSE_EXIT_SELF = 61 🔗

实验性： The reason this notification is sent may change in the future.

当鼠标光标离开控件的可见区域时发送，可见区域即未被其他 Control 和 Window 遮挡的区域，需要 mouse_filter 允许事件达到，与控件是否持有焦点无关。

注意：CanvasItem.z_index 不影响哪个 Control 会收到该通知。

另见 NOTIFICATION_MOUSE_EXIT。

NOTIFICATION_FOCUS_ENTER = 43 🔗

当节点获得焦点时发送。

NOTIFICATION_FOCUS_EXIT = 44 🔗

当节点失去焦点时发送。

NOTIFICATION_THEME_CHANGED = 45 🔗

当节点需要刷新其主题项目时发送。发送时机如下：

• 该节点或其任何祖先节点上的 theme 属性被更改。

• 该节点上的 theme_type_variation 属性被更改。

• 该节点的某个主题属性覆盖被更改。

• 该节点进入场景树。

注意：作为一种优化，当该节点在场景树之外时，发生的更改不会发送该通知。相反，所有的主题项更新可以在该节点进入场景树时一次性应用。

注意：该通知与 Node.NOTIFICATION_ENTER_TREE 一同发送，因此，如果你是在实例化场景，那么此时子节点尚未初始化。可以在该通知中设置该节点的主题和用脚本创建的节点的主题，如果你想要访问编辑器中添加的子节点，请使用 Node.is_node_ready 确认节点已就绪。

func _notification(what):
    if what == NOTIFICATION_THEME_CHANGED:
        if not is_node_ready():
            await ready # 等待就绪信号。
        $Label.add_theme_color_override("font_color", Color.YELLOW)

NOTIFICATION_SCROLL_BEGIN = 47 🔗

当该节点位于 ScrollContainer 内部时发送，该容器在通过触摸事件拖动该可滚动区域时已开始滚动。通过拖动滚动条滚动、使用鼠标滚轮滚动、或使用键盘/游戏手柄事件滚动时，不会发送该通知。

注意：该信号仅会在 Android、iOS、桌面、Web 平台上发出，在桌面/Web 平台上需要启用 ProjectSettings.input_devices/pointing/emulate_touch_from_mouse。

NOTIFICATION_SCROLL_END = 48 🔗

当该节点位于 ScrollContainer 内部时发送，该容器在通过触摸事件拖动该可滚动区域时已停止滚动。通过拖动滚动条滚动、使用鼠标滚轮滚动、或使用键盘/游戏手柄事件滚动时，不会发送该通知。

注意：该信号仅会在 Android、iOS、桌面、Web 平台上发出，在桌面/Web 平台上需要启用 ProjectSettings.input_devices/pointing/emulate_touch_from_mouse。

NOTIFICATION_LAYOUT_DIRECTION_CHANGED = 49 🔗

当控件的布局方向改变时发送。

属性说明

float anchor_bottom = 0.0 🔗

• float get_anchor(side: Side) const

将节点的底部边缘锚定到父控件的原点、中心或末端。会改变该节点发生移动或改变大小时底部偏移量的更新方式。方便起见，你可以使用 Anchor 常量。

float anchor_left = 0.0 🔗

• float get_anchor(side: Side) const

将节点的左侧边缘锚定到父控件的原点、中心或末端。会改变该节点发生移动或改变大小时左侧偏移量的更新方式。方便起见，你可以使用 Anchor 常量。

float anchor_right = 0.0 🔗

• float get_anchor(side: Side) const

将节点的右侧边缘锚定到父控件的原点、中心或末端。会改变该节点发生移动或改变大小时右侧偏移量的更新方式。方便起见，你可以使用 Anchor 常量。

float anchor_top = 0.0 🔗

• float get_anchor(side: Side) const

将节点的顶部边缘锚定到父控件的原点、中心或末端。会改变该节点发生移动或改变大小时顶部偏移量的更新方式。方便起见，你可以使用 Anchor 常量。

bool auto_translate 🔗

• void set_auto_translate(value: bool)

• bool is_auto_translating()

已弃用： Use Node.auto_translate_mode instead.

切换是否所有文本都应该根据当前区域设置自动变为翻译后的版本。

bool clip_contents = false 🔗

• void set_clip_contents(value: bool)

• bool is_clipping_contents()

渲染基于 CanvasItem 的子节点时，是否应剪裁到该控件的矩形中。如果为 true，则子节点显示在该控件的矩形范围之外的部分，不会渲染，也不会接收输入。

Vector2 custom_minimum_size = Vector2(0, 0) 🔗

• void set_custom_minimum_size(value: Vector2)

• Vector2 get_custom_minimum_size()

节点边界矩形的最小尺寸。如果你将它设置为大于 (0, 0) 的值，节点的边界矩形将始终至少有这个大小。请注意，Control 节点的 get_minimum_size 会返回内部最小尺寸，是由控件中的文本、纹理、样式盒等内容决定的，实际的最小尺寸是该属性与内部最小尺寸中的较大值（见 get_combined_minimum_size）。

FocusMode focus_mode = 0 🔗

• void set_focus_mode(value: FocusMode)

• FocusMode get_focus_mode()

该控件的焦点访问模式（“无”“单击”或“全部”）。只能同时聚焦一个控件，该控件会收到键盘、手柄以及鼠标的信号。

NodePath focus_neighbor_bottom = NodePath("") 🔗

• void set_focus_neighbor(side: Side, neighbor: NodePath)

• NodePath get_focus_neighbor(side: Side) const

告诉 Godot 当用户按下键盘上的下方向键或游戏手柄上的下方向键时，默认应该将焦点移交给哪个节点。你可以通过编辑输入动作 ProjectSettings.input/ui_down 来修改具体的按键。该节点必须为 Control。如果未设置这个属性，Godot 会将焦点移交给该节点下方距离最近的 Control。

NodePath focus_neighbor_left = NodePath("") 🔗

• void set_focus_neighbor(side: Side, neighbor: NodePath)

• NodePath get_focus_neighbor(side: Side) const

告诉 Godot 当用户按下键盘上的左方向键或游戏手柄上的左方向键时，默认应该将焦点移交给哪个节点。你可以通过编辑输入动作 ProjectSettings.input/ui_left 来修改具体的按键。该节点必须为 Control。如果未设置这个属性，Godot 会将焦点移交给该节点左侧距离最近的 Control。

NodePath focus_neighbor_right = NodePath("") 🔗

• void set_focus_neighbor(side: Side, neighbor: NodePath)

• NodePath get_focus_neighbor(side: Side) const

告诉 Godot 当用户按下键盘上的右方向键或游戏手柄上的右方向键时，默认应该将焦点移交给哪个节点。你可以通过编辑输入动作 ProjectSettings.input/ui_right 来修改具体的按键。该节点必须为 Control。如果未设置这个属性，Godot 会将焦点移交给该节点右侧距离最近的 Control。

NodePath focus_neighbor_top = NodePath("") 🔗

• void set_focus_neighbor(side: Side, neighbor: NodePath)

• NodePath get_focus_neighbor(side: Side) const

告诉 Godot 当用户按下键盘上的下方向键或游戏手柄上的下方向键时，默认应该将焦点移交给哪个节点。你可以通过编辑输入动作 ProjectSettings.input/ui_up 来修改具体的按键。该节点必须为 Control。如果未设置这个属性，Godot 会将焦点移交给该节点上方距离最近的 Control。

NodePath focus_next = NodePath("") 🔗

• void set_focus_next(value: NodePath)

• NodePath get_focus_next()

告诉 Godot 在默认情况下，当用户按下键盘上的 Tab 时，应将焦点交给哪个节点。你可以通过编辑 ProjectSettings.input/ui_focus_next 的输入动作来更改按键。

如果未设置此属性，则 Godot 会将根据场景树中的附近节点选择一个“最佳猜测”。

NodePath focus_previous = NodePath("") 🔗

• void set_focus_previous(value: NodePath)

• NodePath get_focus_previous()

告诉 Godot 在默认情况下，当用户按下键盘上的 Shift + Tab 时，应将焦点交给哪个节点。你可以通过编辑 ProjectSettings.input/ui_focus_prev 的输入动作来更改按键。

如果未设置此属性，则 Godot 会将根据场景树中的附近节点选择一个“最佳猜测”。

Vector2 global_position 🔗

• Vector2 get_global_position()

该节点的全局位置，相对于世界（通常为 CanvasLayer）。

GrowDirection grow_horizontal = 1 🔗

• void set_h_grow_direction(value: GrowDirection)

• GrowDirection get_h_grow_direction()

控制水平轴的方向，如果控件的水平最小尺寸更改为大于其当前尺寸，则控件应沿水平轴增长，因为控件始终必须至少为最小尺寸。

GrowDirection grow_vertical = 1 🔗

• void set_v_grow_direction(value: GrowDirection)

• GrowDirection get_v_grow_direction()

控制控件在垂直轴上的方向，如果控件的垂直最小尺寸更改为大于当前尺寸，则控件应沿该方向增大，因为控件始终必须至少为最小尺寸。

LayoutDirection layout_direction = 0 🔗

• void set_layout_direction(value: LayoutDirection)

• LayoutDirection get_layout_direction()

控制布局方向和文本书写方向。某些语言需要从右至左的布局（例如阿拉伯语和希伯来语）。

bool localize_numeral_system = true 🔗

• void set_localize_numeral_system(value: bool)

• bool is_localizing_numeral_system()

如果为 true，则会自动将代码行号、列表索引号、SpinBox 和 ProgressBar 的值，从阿拉伯数字（0..9）转换为当前区域设置所使用的记数系统。

注意：不会自动转换文本中的数字，可以使用 TextServer.format_number 手动转换。

CursorShape mouse_default_cursor_shape = 0 🔗

• void set_default_cursor_shape(value: CursorShape)

• CursorShape get_default_cursor_shape()

此控件的默认光标形状。对于 Godot 插件和使用系统鼠标光标的应用程序或游戏很有用。

注意：在 Linux 上，形状可能会有所不同，具体取决于系统的光标主题。

MouseFilter mouse_filter = 0 🔗

• void set_mouse_filter(value: MouseFilter)

• MouseFilter get_mouse_filter()

控制控件是否能够通过 _gui_input 接收鼠标按钮输入事件，以及如何处理这些事件。还控制控件是否能接收 mouse_entered 和 mouse_exited 信号。参阅常量来了解每个常量的作用。

bool mouse_force_pass_scroll_events = true 🔗

• void set_force_pass_scroll_events(value: bool)

• bool is_force_pass_scroll_events()

启用后，即使 mouse_filter 被设置为 MOUSE_FILTER_STOP，由 _gui_input 处理的滚轮事件也会被传递给父控件。由于它默认为“真”，这允许嵌套的可滚动容器可以开箱即用。

如果不希望滚动事件进入 Node._unhandled_input 处理，则应该在用户界面的根部禁用它。

float offset_bottom = 0.0 🔗

• void set_offset(side: Side, offset: float)

• float get_offset(offset: Side) const

该节点底部边缘与其父控件之间的距离，基于 anchor_bottom。

偏移量通常由一个或多个父 Container 节点控制，因此如果你的节点是 Container 的直接子节点，则不应进行手动修改。移动节点或调整节点大小时，偏移量会自动更新。

float offset_left = 0.0 🔗

• void set_offset(side: Side, offset: float)

• float get_offset(offset: Side) const

该节点左侧边缘与其父控件之间的距离，基于 anchor_left。

偏移量通常由一个或多个父 Container 节点控制，因此如果你的节点是 Container 的直接子节点，则不应进行手动修改。移动节点或调整节点大小时，偏移量会自动更新。

float offset_right = 0.0 🔗

• void set_offset(side: Side, offset: float)

• float get_offset(offset: Side) const

该节点右侧边缘与其父控件之间的距离，基于 anchor_right。

偏移量通常由一个或多个父 Container 节点控制，因此如果你的节点是 Container 的直接子节点，则不应进行手动修改。移动节点或调整节点大小时，偏移量会自动更新。

float offset_top = 0.0 🔗

• void set_offset(side: Side, offset: float)

• float get_offset(offset: Side) const

该节点顶部边缘与其父控件之间的距离，基于 anchor_top。

偏移量通常由一个或多个父 Container 节点控制，因此如果你的节点是 Container 的直接子节点，则不应进行手动修改。移动节点或调整节点大小时，偏移量会自动更新。

Vector2 pivot_offset = Vector2(0, 0) 🔗

• void set_pivot_offset(value: Vector2)

• Vector2 get_pivot_offset()

默认情况下，该节点的轴心位于左上角。更改 rotation 或 scale 时，将围绕该轴心进行旋转或缩放。如果将该属性设置为 size / 2，则围绕的是该控件的中心点。

Vector2 position = Vector2(0, 0) 🔗

• Vector2 get_position()

该节点的位置，相对于父节点。对应的是矩形的左上角。该属性不受 pivot_offset 的影响。

float rotation = 0.0 🔗

• void set_rotation(value: float)

• float get_rotation()

该节点围绕其轴心的旋转，单位为弧度。要更改轴心的位置，请参阅 pivot_offset。

注意：该属性在检查器中以度为单位进行编辑。如果要在脚本中使用度数，请使用 rotation_degrees。

float rotation_degrees 🔗

• void set_rotation_degrees(value: float)

• float get_rotation_degrees()

辅助属性，用于按度数访问 rotation 而不是弧度数。

Vector2 scale = Vector2(1, 1) 🔗

• void set_scale(value: Vector2)

• Vector2 get_scale()

节点的缩放，相对于它的 size。更改该属性以围绕其 pivot_offset 缩放节点。该 Control 的 tooltip_text 也将根据该值进行缩放。

注意：该属性主要用于动画用途。要在项目中支持多种分辨率，请使用 文档 中所述的合适的视口拉伸模式，而不是单独缩放控件。

注意：FontFile.oversampling 不考虑 Control scale。这意味着放大/缩小会导致位图字体和光栅化（非 MSDF）动态字体显得模糊或像素化。为确保无论缩放比例如何，文本都保持清晰，你可以通过启用 ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field（仅适用于默认项目字体）；或在自定义字体的 DynamicFont 的导入选项中，启用多通道有符号距离场来启用 MSDF 字体渲染。对于系统字体，可以在检查器中启用 SystemFont.multichannel_signed_distance_field。

注意：如果该 Control 节点是 Container 节点的子节点，则场景实例化时，缩放将重置为 Vector2(1, 1)。要在实例化时设置控件的缩放，请使用 await get_tree().process_frame 等待一帧，然后再设置其 scale 属性。

Node shortcut_context 🔗

• void set_shortcut_context(value: Node)

• Node get_shortcut_context()

该 Node 必须是被聚焦 Control 的父节点，才能激活快捷方式。如果为 null，则可以在任何控件获得焦点时激活该快捷方式（全局快捷方式）。这允许快捷方式只在用户聚焦 GUI 的特定区域时才被接受。

Vector2 size = Vector2(0, 0) 🔗

• Vector2 get_size()

该节点的边界矩形的大小，使用该节点的坐标系。Container 节点会自动更新此属性。

BitField[SizeFlags] size_flags_horizontal = 1 🔗

• void set_h_size_flags(value: BitField[SizeFlags])

• BitField[SizeFlags] get_h_size_flags()

告诉父 Container 节点应如何调整尺寸并将其放置在 X 轴上。请使用 SizeFlags 常量的组合来更改标志。查看常量以了解每个常量的作用。

float size_flags_stretch_ratio = 1.0 🔗

• void set_stretch_ratio(value: float)

• float get_stretch_ratio()

如果该节点及其至少一个邻居节点使用 SIZE_EXPAND 大小标志，则父 Container 将根据该属性让它占用更多或更少的空间。如果该节点的拉伸比为 2，其邻居节点的拉伸比为 1，则该节点将占用三分之二的可用空间。

BitField[SizeFlags] size_flags_vertical = 1 🔗

• void set_v_size_flags(value: BitField[SizeFlags])

• BitField[SizeFlags] get_v_size_flags()

告诉父 Container 节点应如何调整尺寸并将其放置在 Y 轴上。请使用 SizeFlags 常量的组合来更改标志。查看常量以了解每个常量的作用。

Theme theme 🔗

• void set_theme(value: Theme)

• Theme get_theme()

该节点及其子 Control 和 Window 所使用的 Theme 资源。如果子节点也设置了 Theme 资源，则会合并主题项，子节点的定义优先级更高。

注意：除非 Window 为嵌入式，否则窗口样式无效。

StringName theme_type_variation = &"" 🔗

• void set_theme_type_variation(value: StringName)

• StringName get_theme_type_variation()

该 Control 用于查找其自有的主题项的主题类型变体的名称。当为空时，将使用节点的类名（例如 Button 用于 Button 控件），以及所有父类的类名（按继承顺序）。

设置后，该属性将最高优先级赋予指定名称的类型。这种类型又可以扩展另一种类型，形成依赖链。参见 Theme.set_type_variation。如果使用该类型或其基类型无法找到主题项，则查找会回退到依赖类名查找。

注意：要查找 Control 自有的项目，请使用各种 get_theme_* 方法且无需指定 theme_type。

注意：主题项按树状顺序查找，从分支到根，其中每个 Control 节点的 theme 属性都将被检查。最早匹配任意类型名称/类名称的项将被返回。最后检查项目级的主题和默认主题。

String tooltip_text = "" 🔗

• void set_tooltip_text(value: String)

• String get_tooltip_text()

默认工具提示文本。如果 mouse_filter 属性不是 MOUSE_FILTER_IGNORE，则当用户的鼠标光标在此控件上停留片刻时，将出现工具提示。可以使用 ProjectSettings.gui/timers/tooltip_delay_sec 选项更改工具提示出现所需的时间。另见 get_tooltip。

工具提示弹出窗口将使用默认实现，或者使用通过覆盖 _make_custom_tooltip 提供的自定义实现。默认工具提示包括一个 PopupPanel 和 Label，其主题属性可以使用 Theme 方法分别对 "TooltipPanel" 和 "TooltipLabel" 进行自定义。例如：

GDScriptC#

var style_box = StyleBoxFlat.new()
style_box.set_bg_color(Color(1, 1, 0))
style_box.set_border_width_all(2)
# 我们在这里假设`Theme`属性已经被事先分配了一个自定义的主题。
theme.set_stylebox("panel", "TooltipPanel", style_box)
theme.set_color("font_color", "TooltipLabel", Color(0, 1, 1))

var styleBox = new StyleBoxFlat();
styleBox.SetBgColor(new Color(1, 1, 0));
styleBox.SetBorderWidthAll(2);
// 我们在这里假设`Theme`属性已经被事先分配了一个自定义的主题。
Theme.SetStyleBox("panel", "TooltipPanel", styleBox);
Theme.SetColor("font_color", "TooltipLabel", new Color(0, 1, 1));

方法说明

bool _can_drop_data(at_position: Vector2, data: Variant) virtual const 🔗

Godot 调用这个方法来检查是否能够将来自某个控件 _get_drag_data 方法的 data 拖放到 at_position。at_position 使用的是这个控件的局部坐标系。

这个方法应该只用于检查数据。请在 _drop_data 中处理数据。

GDScriptC#

func _can_drop_data(position, data):
    # 如果和位置相关就检查 position
    # 否则只检查 data 即可
    return typeof(data) == TYPE_DICTIONARY and data.has("expected")

public override bool _CanDropData(Vector2 atPosition, Variant data)
{
    // 如果和位置相关就检查 position
    // 否则只检查 data 即可
    return data.VariantType == Variant.Type.Dictionary && data.AsGodotDictionary().ContainsKey("expected");
}

void _drop_data(at_position: Vector2, data: Variant) virtual 🔗

Godot 调用该方法把 data 传给你，这是从某个控件的 _get_drag_data 获得的结果。Godot 首先会调用 _can_drop_data 来检查是否允许把 data 拖放到 at_position，这里的 at_position 使用的是这个控件的局部坐标系。

GDScriptC#

func _can_drop_data(position, data):
    return typeof(data) == TYPE_DICTIONARY and data.has("color")
func _drop_data(position, data):
    var color = data["color"]

public override bool _CanDropData(Vector2 atPosition, Variant data)
{
    return data.VariantType == Variant.Type.Dictionary && dict.AsGodotDictionary().ContainsKey("color");
}
public override void _DropData(Vector2 atPosition, Variant data)
{
    Color color = data.AsGodotDictionary()["color"].AsColor();
}

Variant _get_drag_data(at_position: Vector2) virtual 🔗

Godot 调用该方法来获取数据，这个数据将用于拖动操作，放置到期望放置数据的控件上。如果没有要拖动的数据，则返回 null。想要接收拖放数据的控件应该实现 _can_drop_data 和 _drop_data。at_position 是该控件的局部位置。可以使用 force_drag 强制拖动。

可以使用 set_drag_preview 设置跟随鼠标显示数据的预览。本方法中非常适合设置这个预览。

GDScriptC#

func _get_drag_data(position):
    var mydata = make_data() # This is your custom method generating the drag data.
    set_drag_preview(make_preview(mydata)) # 这是你生成拖动数据预览的自定义方法。
    return mydata

public override Variant _GetDragData(Vector2 atPosition)
{
    var myData = MakeData(); // This is your custom method generating the drag data.
    SetDragPreview(MakePreview(myData)); // 这是你生成拖动数据预览的自定义方法。
    return myData;
}

Vector2 _get_minimum_size() virtual const 🔗

由用户实现的虚方法。返回此控件的最小大小。替代 custom_minimum_size，以用于通过代码控制最小尺寸。实际的最小尺寸将是这两者的最大值（分别在每个轴上）。

如果未覆盖，则默认为 Vector2.ZERO。

注意：当脚本被附加到已经覆盖其最小大小的 Control 节点（例如 Label、Button、PanelContainer 等）时，该方法将不会被调用。它只能用于最基本的 GUI 节点，如 Control、Container、Panel 等。

String _get_tooltip(at_position: Vector2) virtual const 🔗

用户实现的虚方法。返回位于控件局部坐标系中 at_position 位置的工具提示文本，工具提示一般会在鼠标停留在该控件上时显示。见 get_tooltip。

注意：如果返回的是空 String，则不会显示工具提示。

void _gui_input(event: InputEvent) virtual 🔗

由用户实现的虚方法。使用此方法处理和接受 UI 元素上的输入。请参阅 accept_event。

点击控件的用法示例：

GDScriptC#

func _gui_input(event):
    if event is InputEventMouseButton:
        if event.button_index == MOUSE_BUTTON_LEFT and event.pressed:
            print("我已被点击 D:")

public override void _GuiInput(InputEvent @event)
{
    if (@event is InputEventMouseButton mb)
    {
        if (mb.ButtonIndex == MouseButton.Left && mb.Pressed)
        {
            GD.Print("我已被点击 D:");
        }
    }
}

如果出现以下情况，则不会触发该事件：

* 在控件外点击（参阅_has_point）；

* 控件将 mouse_filter 设置为 MOUSE_FILTER_IGNORE；

* 控件被其上的另一个 Control 阻挡，该控件没有将 mouse_filter 设置为 MOUSE_FILTER_IGNORE；

* 控件的父级已将 mouse_filter 设置为 MOUSE_FILTER_STOP 或已接受该事件；

* 它发生在父级的矩形之外，并且父级已启用 clip_contents。

注意：事件位置相对于该控件原点。

bool _has_point(point: Vector2) virtual const 🔗

由用户实现的虚方法。返回给定的 point 是否在该控件内。

如果没有被覆盖，则默认行为是检查该点是否在控件的 Rect 内。

注意：如果要检查一个点是否在该控件内部，可以使用 Rect2(Vector2.ZERO, size).has_point(point)。

Object _make_custom_tooltip(for_text: String) virtual const 🔗

由用户实现的虚方法。返回一个 Control 节点，该节点取代默认节点以用作工具提示。for_text 包含 tooltip_text 属性的内容。

返回的节点必须是 Control 类型或 Control 派生类型。它可以有任何类型的子节点。当工具提示消失时它会被释放，因此请确保你始终提供一个新实例（如果你想使用场景树中预先存在的节点，你可以复制它并传递复制的实例）。当返回 null 或非控制节点时，将使用默认的工具提示。

返回的节点将作为子节点添加到 PopupPanel，因此你应该只提供该面板的内容。该 PopupPanel 可以使用 Theme.set_stylebox 为类型 "TooltipPanel" 设置主题（参见 tooltip_text 示例）。

注意：工具提示会被缩小到最小大小。如果你想确保它完全可见，你可能需要将其 custom_minimum_size 设置为非零值。

注意：返回时节点（和任何相关的子节点）应该是 CanvasItem.visible，否则，实例化它的视口将无法可靠地计算它的最小大小。

自定义构造节点的用法示例：

GDScriptC#

func _make_custom_tooltip(for_text):
    var label = Label.new()
    label.text = for_text
    return label

public override Control _MakeCustomTooltip(string forText)
{
    var label = new Label();
    label.Text = forText;
    return label;
}

自定义场景实例的使用示例：

GDScriptC#

func _make_custom_tooltip(for_text):
    var tooltip = preload("res://some_tooltip_scene.tscn").instantiate()
    tooltip.get_node("Label").text = for_text
    return tooltip

public override Control _MakeCustomTooltip(string forText)
{
    Node tooltip = ResourceLoader.Load<PackedScene>("res://some_tooltip_scene.tscn").Instantiate();
    tooltip.GetNode<Label>("Label").Text = forText;
    return tooltip;
}

Array[Vector3i] _structured_text_parser(args: Array, text: String) virtual const 🔗

用户定义的 BiDi 算法覆盖函数。

返回 Vector3i 文本范围和文本基础方向的 Array，顺序为从左至右。这些范围应该覆盖完整的来源文本 text，不应该存在重叠。BiDi 算法会对每个范围单独应用。

void accept_event() 🔗

将输入事件标记为已处理。一旦接受输入事件，传播就会停止，不会再传播到正在侦听 Node._unhandled_input 和 Node._unhandled_key_input 的节点。

注意：不会影响 Input 中的方法，只会影响事件的传播。

void add_theme_color_override(name: StringName, color: Color) 🔗

为名称为 name 的主题 Color 创建本地覆盖项。为控件获取主题项目时，本地覆盖项始终优先。覆盖项可以使用 remove_theme_color_override 移除。

另见 get_theme_color。

覆盖标签颜色并在之后重置的示例：

GDScriptC#

# 存在名叫“MyLabel”的子 Label 节点，使用自定义的值覆盖其字体颜色。
$MyLabel.add_theme_color_override("font_color", Color(1, 0.5, 0))
# 重置该子标签的字体颜色。
$MyLabel.remove_theme_color_override("font_color")
# 也可以使用 Label 类型的默认值覆盖。
$MyLabel.add_theme_color_override("font_color", get_theme_color("font_color", "Label"))

// 存在名叫“MyLabel”的子 Label 节点，使用自定义的值覆盖其字体颜色。
GetNode<Label>("MyLabel").AddThemeColorOverride("font_color", new Color(1, 0.5f, 0));
// 重置该子标签的字体颜色。
GetNode<Label>("MyLabel").RemoveThemeColorOverride("font_color");
// 也可以使用 Label 类型的默认值覆盖。
GetNode<Label>("MyLabel").AddThemeColorOverride("font_color", GetThemeColor("font_color", "Label"));

void add_theme_constant_override(name: StringName, constant: int) 🔗

为名称为 name 的主题常量创建本地覆盖项。为控件获取主题项目时，本地覆盖项始终优先。覆盖项可以使用 remove_theme_constant_override 移除。

另见 get_theme_constant。

void add_theme_font_override(name: StringName, font: Font) 🔗

为名称为 name 的主题 Font 创建本地覆盖项。为控件获取主题项目时，本地覆盖项始终优先。覆盖项可以使用 remove_theme_font_override 移除。

另见 get_theme_font。

void add_theme_font_size_override(name: StringName, font_size: int) 🔗

为名称为 name 的主题字体大小创建本地覆盖项。为控件获取主题项目时，本地覆盖项始终优先。覆盖项可以使用 remove_theme_font_size_override 移除。

另见 get_theme_font_size。

void add_theme_icon_override(name: StringName, texture: Texture2D) 🔗

为名称为 name 的主题图标创建本地覆盖项。为控件获取主题项目时，本地覆盖项始终优先。覆盖项可以使用 remove_theme_icon_override 移除。

另见 get_theme_icon。

void add_theme_stylebox_override(name: StringName, stylebox: StyleBox) 🔗

为名称为 name 的主题 StyleBox 创建本地覆盖项。为控件获取主题项目时，本地覆盖项始终优先。覆盖项可以使用 remove_theme_stylebox_override 移除。

另见 get_theme_stylebox。

通过创建副本来修改 StyleBox 属性的示例：

GDScriptC#

# 以下代码片段要求子节点 MyButton 分配了 StyleBoxFlat。
# 资源是跨实例共享的，因此我们需要制作其副本
# 来避免修改其他所有按钮的外观。
var new_stylebox_normal = $MyButton.get_theme_stylebox("normal").duplicate()
new_stylebox_normal.border_width_top = 3
new_stylebox_normal.border_color = Color(0, 1, 0.5)
$MyButton.add_theme_stylebox_override("normal", new_stylebox_normal)
# 移除样式盒覆盖项。
$MyButton.remove_theme_stylebox_override("normal")

// 以下代码片段要求子节点 MyButton 分配了 StyleBoxFlat。
// 资源是跨实例共享的，因此我们需要制作其副本
// 来避免修改其他所有按钮的外观。
StyleBoxFlat newStyleboxNormal = GetNode<Button>("MyButton").GetThemeStylebox("normal").Duplicate() as StyleBoxFlat;
newStyleboxNormal.BorderWidthTop = 3;
newStyleboxNormal.BorderColor = new Color(0, 1, 0.5f);
GetNode<Button>("MyButton").AddThemeStyleboxOverride("normal", newStyleboxNormal);
// 移除样式盒覆盖项。
GetNode<Button>("MyButton").RemoveThemeStyleboxOverride("normal");

void begin_bulk_theme_override() 🔗

防止 *_theme_*_override 方法发出 NOTIFICATION_THEME_CHANGED，直到 end_bulk_theme_override 被调用。

void end_bulk_theme_override() 🔗

结束批量主题覆盖更新。见 begin_bulk_theme_override。

Control find_next_valid_focus() const 🔗

找到下一个可以接受焦点的 Control，在树的下方。

Control find_prev_valid_focus() const 🔗

找到上一个可以接受焦点的 Control，在树的上方。

Control find_valid_focus_neighbor(side: Side) const 🔗

查找指定 Side 上可以接收焦点的下一个 Control。

注意：这与 get_focus_neighbor 不同，后者返回指定焦点邻居的路径。

void force_drag(data: Variant, preview: Control) 🔗

通过传递 data 和 preview 强制拖动并绕过 _get_drag_data 和 set_drag_preview。即使鼠标既没有在该控件悬停也没有在该控件上按下，拖动都将开始。

方法 _can_drop_data 和 _drop_data 必须在想要接收拖放数据的控件上实现。

float get_anchor(side: Side) const 🔗

返回指定 Side 的锚点。用于 anchor_bottom、anchor_left、anchor_right 和 anchor_top 的取值方法。

Vector2 get_begin() const 🔗

返回 offset_left 和 offset_top。另请参阅 position。

Vector2 get_combined_minimum_size() const 🔗

返回 custom_minimum_size 和 get_minimum_size 的组合最小大小。

CursorShape get_cursor_shape(position: Vector2 = Vector2(0, 0)) const 🔗

返回控件在鼠标悬停时显示的鼠标指针形状。见 CursorShape。

Vector2 get_end() const 🔗

返回 offset_right 和 offset_bottom。

NodePath get_focus_neighbor(side: Side) const 🔗

返回指定 Side 的焦点邻居。用于 focus_neighbor_bottom、focus_neighbor_left、focus_neighbor_right 和 focus_neighbor_top 的取值方法。

注意：要查找特定 Side 上的下一个 Control，即使未指定邻居，也请使用 find_valid_focus_neighbor。

Rect2 get_global_rect() const 🔗

返回控件相对于所属画布的位置和大小。参见 global_position 和 size。

注意：如果节点本身或节点与画布之间的任何父级 CanvasItem 具有非默认旋转或倾斜，则生成的大小可能没有意义。

注意：将 Viewport.gui_snap_controls_to_pixels 设置为 true 会导致显示的控件和返回的 Rect2 之间的舍入不准确。

Vector2 get_minimum_size() const 🔗

返回该控件的最小尺寸。见 custom_minimum_size。

float get_offset(offset: Side) const 🔗

返回指定 Side 的偏移。这是 offset_bottom、offset_left、offset_right 和 offset_top 的 getter 方法。

Vector2 get_parent_area_size() const 🔗

返回父控件中占用的宽度/高度。

Control get_parent_control() const 🔗

返回父控制节点。

Rect2 get_rect() const 🔗

返回控件在包含节点的坐标系中的位置和大小。参见 position、scale 和 size。

注意：如果 rotation 不是默认的旋转，那么得到的大小是没有意义的。

注意：将 Viewport.gui_snap_controls_to_pixels 设置为 true，会导致显示的控件和返回的 Rect2 之间的舍入不准确。

Vector2 get_screen_position() const 🔗

返回该 Control 在全局屏幕坐标系中的位置（即考虑窗口的位置）。主要用于编辑器插件。

如果窗口是嵌入式的，则等于 global_position（见 Viewport.gui_embed_subwindows）。

显示弹出框的用法示例：

popup_menu.position = get_screen_position() + get_local_mouse_position()
popup_menu.reset_size()
popup_menu.popup()

Color get_theme_color(name: StringName, theme_type: StringName = &””) const 🔗

从树中第一个匹配的 Theme 返回 Color，该 Theme 中应存在指定名称 name 和主题类型 theme_type 的颜色项。如果省略 theme_type 则会使用当前控件的类名，如果定义了 theme_type_variation 则会优先使用。如果该类型为类名，则还会按照继承顺序检查父类。如果该类型为变种，则还会按照依赖顺序检查基础类型，然后再检查该控件的类名及其父类。

会首先考虑当前控件的本地覆盖项（见 add_theme_color_override），然后才是其 theme。各个父控件及其 theme 在当前控件之后考虑；会跳过没有 theme 的控件。如果树中没有匹配的 Theme，则会使用自定义项目 Theme（见 ProjectSettings.gui/theme/custom）和默认 Theme（见 ThemeDB）。

GDScriptC#

func _ready():
    # 获取当前 Control 类中定义的字体颜色，前提是存在。
    modulate = get_theme_color("font_color")
    # 获取 Button 类中定义的字体颜色。
    modulate = get_theme_color("font_color", "Button")

public override void _Ready()
{
    // 获取当前 Control 类中定义的字体颜色，前提是存在。
    Modulate = GetThemeColor("font_color");
    // 获取 Button 类中定义的字体颜色。
    Modulate = GetThemeColor("font_color", "Button");
}

int get_theme_constant(name: StringName, theme_type: StringName = &””) const 🔗

从树中第一个匹配的 Theme 返回常量，该 Theme 中应存在指定名称 name 和主题类型 theme_type 的常量项。

详情请参阅 get_theme_color。

float get_theme_default_base_scale() const 🔗

从树中第一个匹配的 Theme 返回默认基础缩放值，该 Theme 中应存在有效的 Theme.default_base_scale 值。

详情请参阅 get_theme_color。

Font get_theme_default_font() const 🔗

从树中第一个匹配的 Theme 返回默认字体，该 Theme 中应存在有效的 Theme.default_font 值。

详情请参阅 get_theme_color。

int get_theme_default_font_size() const 🔗

从树中第一个匹配的 Theme 返回默认字体大小，该 Theme 中应存在有效的 Theme.default_font_size 值。

详情请参阅 get_theme_color。

Font get_theme_font(name: StringName, theme_type: StringName = &””) const 🔗

从树中第一个匹配的 Theme 返回 Font，该 Theme 中应存在指定名称 name 和主题类型 theme_type 的字体项。

详情请参阅 get_theme_color。

int get_theme_font_size(name: StringName, theme_type: StringName = &””) const 🔗

从树中第一个匹配的 Theme 返回字体大小，该 Theme 中应存在指定名称 name 和主题类型 theme_type 的字体大小项。

详情请参阅 get_theme_color。

Texture2D get_theme_icon(name: StringName, theme_type: StringName = &””) const 🔗

从树中第一个匹配的 Theme 返回图标，该 Theme 中应存在指定名称 name 和主题类型 theme_type 的图标项。

详情请参阅 get_theme_color。

StyleBox get_theme_stylebox(name: StringName, theme_type: StringName = &””) const 🔗

从树中第一个匹配的 Theme 返回 StyleBox，该 Theme 中应存在指定名称 name 和主题类型 theme_type 的样式盒项。

详情请参阅 get_theme_color。

String get_tooltip(at_position: Vector2 = Vector2(0, 0)) const 🔗

返回位于该控件局部坐标系中 at_position 位置的工具提示文本，工具提示一般会在鼠标停留在该控件上时显示。默认情况下返回的是 tooltip_text。

覆盖这个方法可以自定义行为。见 _get_tooltip。

注意：如果返回的是空 String，则不会显示工具提示。

void grab_click_focus() 🔗

创建一个尝试点击控件的 InputEventMouseButton。如果收到该事件，则该控件将获得焦点。

GDScriptC#

func _process(delta):
    grab_click_focus() # 点击另一个控制节点时，将改为点击该节点。

public override void _Process(double delta)
{
    GrabClickFocus(); // 点击另一个控制节点时，将改为点击该节点。
}

void grab_focus() 🔗

从别的控件上窃取焦点，从而成为聚焦的控件（见 focus_mode）。

注意：这个方法与 Object.call_deferred 配合使用会更加可靠，尤其是在 Node._ready 中调用时。

bool has_focus() const 🔗

如果这是当前的焦点控件，则返回 true。见 focus_mode。

bool has_theme_color(name: StringName, theme_type: StringName = &””) const 🔗

如果树中存在匹配的 Theme 则返回 true，该 Theme 中应存在指定名称 name 和主题类型 theme_type 的颜色项。

详情请参阅 get_theme_color。

bool has_theme_color_override(name: StringName) const 🔗

如果该 Control 节点中存在名为指定 name 的主题 Color 本地覆盖项，则返回 true。

详情请参阅 add_theme_color_override。

bool has_theme_constant(name: StringName, theme_type: StringName = &””) const 🔗

如果树中存在匹配的 Theme 则返回 true，该 Theme 中应存在指定名称 name 和主题类型 theme_type 的常量项。

详情请参阅 get_theme_color。

bool has_theme_constant_override(name: StringName) const 🔗

如果该 Control 节点中存在名为指定 name 的主题常量本地覆盖项，则返回 true。

详情请参阅 add_theme_constant_override。

bool has_theme_font(name: StringName, theme_type: StringName = &””) const 🔗

如果树中存在匹配的 Theme 则返回 true，该 Theme 中应存在指定名称 name 和主题类型 theme_type 的字体项。

详情请参阅 get_theme_color。

bool has_theme_font_override(name: StringName) const 🔗

如果该 Control 节点中存在名为指定 name 的主题 Font 本地覆盖项，则返回 true。

详情请参阅 add_theme_font_override。

bool has_theme_font_size(name: StringName, theme_type: StringName = &””) const 🔗

如果树中存在匹配的 Theme 则返回 true，该 Theme 中应存在指定名称 name 和主题类型 theme_type 的字体大小项。

详情请参阅 get_theme_color。

bool has_theme_font_size_override(name: StringName) const 🔗

如果该 Control 节点中存在名为指定 name 的主题字体大小本地覆盖项，则返回 true。

详情请参阅 add_theme_font_size_override。

bool has_theme_icon(name: StringName, theme_type: StringName = &””) const 🔗

如果树中存在匹配的 Theme 则返回 true，该 Theme 中应存在指定名称 name 和主题类型 theme_type 的图标项。

详情请参阅 get_theme_color。

bool has_theme_icon_override(name: StringName) const 🔗

如果该 Control 节点中存在名为指定 name 的主题图标本地覆盖项，则返回 true。

详情请参阅 add_theme_icon_override。

bool has_theme_stylebox(name: StringName, theme_type: StringName = &””) const 🔗

如果树中存在匹配的 Theme 则返回 true，该 Theme 中应存在指定名称 name 和主题类型 theme_type 的样式盒项。

详情请参阅 get_theme_color。

bool has_theme_stylebox_override(name: StringName) const 🔗

如果该 Control 节点中存在名为指定 name 的主题 StyleBox 本地覆盖项，则返回 true。

详情请参阅 add_theme_stylebox_override。

bool is_drag_successful() const 🔗

如果拖放操作成功则返回 true，是 Viewport.gui_is_drag_successful 的替代方案。

建议与 Node.NOTIFICATION_DRAG_END 配合使用。

bool is_layout_rtl() const 🔗

如果布局是从右至左的，则返回 true。

void release_focus() 🔗

放弃焦点。不会让其他控件能够接收键盘输入。

void remove_theme_color_override(name: StringName) 🔗

移除名为指定 name 的主题 Color 本地覆盖项，该覆盖项由 add_theme_color_override 或检查器面板添加的。

void remove_theme_constant_override(name: StringName) 🔗

移除名为指定 name 的主题常量本地覆盖项，该覆盖项由 add_theme_constant_override 或检查器面板添加的。

void remove_theme_font_override(name: StringName) 🔗

移除名为指定 name 的主题 Font 本地覆盖项，该覆盖项由 add_theme_font_override 或检查器面板添加的。

void remove_theme_font_size_override(name: StringName) 🔗

移除名为指定 name 的主题字体大小本地覆盖项，该覆盖项由 add_theme_font_size_override 或检查器面板添加的。

void remove_theme_icon_override(name: StringName) 🔗

移除名为指定 name 的主题图标本地覆盖项，该覆盖项由 add_theme_icon_override 或检查器面板添加的。

void remove_theme_stylebox_override(name: StringName) 🔗

移除名为指定 name 的主题 StyleBox 本地覆盖项，该覆盖项由 add_theme_stylebox_override 或检查器面板添加的。

void reset_size() 🔗

将大小重置为 get_combined_minimum_size。等价于调用 set_size(Vector2())（或任何小于最小值的大小）。

void set_anchor(side: Side, anchor: float, keep_offset: bool = false, push_opposite_anchor: bool = true) 🔗

将指定 Side 的锚点设置为 anchor。用于 anchor_bottom、anchor_left、anchor_right 和 anchor_top 的设值函数。

如果 keep_offset 为 true，则偏移量不会在该操作后更新。

如果 push_opposite_anchor 为 true，并且相对的锚点与该锚点重叠，则相对的锚点的值将被覆盖。例如，当将左锚点设置为 1 且右锚点的值为 0.5 时，右锚点的值也将为 1。如果 push_opposite_anchor 为 false，则左锚点的值将为 0.5。

void set_anchor_and_offset(side: Side, anchor: float, offset: float, push_opposite_anchor: bool = false) 🔗

工作原理与 set_anchor 相同，但取代 keep_offset 参数和自动更新的偏移，它允许你自己设置偏移量（参见 set_offset）。

void set_anchors_and_offsets_preset(preset: LayoutPreset, resize_mode: LayoutPresetMode = 0, margin: int = 0) 🔗

设置锚点预设和偏移预设。参见 set_anchors_preset 和 set_offsets_preset。

void set_anchors_preset(preset: LayoutPreset, keep_offsets: bool = false) 🔗

将锚点设置为 LayoutPreset 枚举中的 preset。这是相当于在 2D 编辑器中使用布局菜单的代码。

如果 keep_offsets 为 true，则控件的位置也将被更新。

void set_begin(position: Vector2) 🔗

同时设置 offset_left 和 offset_top。相当于改变 position。

void set_drag_forwarding(drag_func: Callable, can_drop_func: Callable, drop_func: Callable) 🔗

转发该控件的 _get_drag_data、_can_drop_data 和 _drop_data 虚函数的处理，以委托给可调用体。

对于每个参数，如果不为空，则使用委托的可调用体，否则使用本地（虚）函数。

每个可调用体的函数格式应该与上面描述的虚函数完全相同。

void set_drag_preview(control: Control) 🔗

在鼠标指针处显示给定的控件。调用此方法的好时机是在 _get_drag_data 中。控件不得位于场景树中。你不应释放控件，也不应在拖动持续时间之外保留对控件的引用。拖拽结束后它会自动删除。

GDScriptC#

@export var color = Color(1, 0, 0, 1)
func _get_drag_data(position):
    #使用不在树中的控件
    var cpb = ColorPickerButton.new()
    cpb.color = color
    cpb.size = Vector2(50, 50)
    set_drag_preview(cpb)
    return color

[Export]
private Color _color = new Color(1, 0, 0, 1);
public override Variant _GetDragData(Vector2 atPosition)
{
    // 使用不在树中的控件
    var cpb = new ColorPickerButton();
    cpb.Color = _color;
    cpb.Size = new Vector2(50, 50);
    SetDragPreview(cpb);
    return _color;
}

void set_end(position: Vector2) 🔗

同时设置 offset_right 和 offset_bottom。

void set_focus_neighbor(side: Side, neighbor: NodePath) 🔗

将指定 Side 的焦点邻居设置为节点路径 neighbor 处的 Control。这是 focus_neighbor_bottom、focus_neighbor_left、focus_neighbor_right 和 focus_neighbor_top 的 setter 方法。

void set_global_position(position: Vector2, keep_offsets: bool = false) 🔗

将 global_position 设置为给定的 position。

如果 keep_offsets 为 true，则将更新控件的锚点而不是偏移量。

void set_offset(side: Side, offset: float) 🔗

将指定 Side 的偏移设置为 offset。用于 offset_bottom、offset_left、offset_right 和 offset_top 的设值方法。

void set_offsets_preset(preset: LayoutPreset, resize_mode: LayoutPresetMode = 0, margin: int = 0) 🔗

将偏移设置为 LayoutPreset 枚举中的 preset。这是相当于在 2D 编辑器中使用布局菜单的代码。

将参数 resize_mode 与 LayoutPresetMode 中的常量一起使用，以更好地确定 Control 的最终大小。如果与更改尺寸大小的预设一起使用，则将忽略常量尺寸大小，例如 PRESET_LEFT_WIDE。

使用参数 margin 来确定 Control 和边缘之间的间隙。

void set_position(position: Vector2, keep_offsets: bool = false) 🔗

将 position 设置为给定的 position。

如果 keep_offsets 为 true，则将更新控件的锚点而不是偏移量。

void set_size(size: Vector2, keep_offsets: bool = false) 🔗

设置大小（参见 size）。

如果 keep_offsets 为 true，则将更新控件的锚点而不是偏移量。

void update_minimum_size() 🔗

使该节点和直至顶级的父节点中的大小缓存无效。旨在当返回值更改时与 get_minimum_size 一起使用。直接设置 custom_minimum_size 将自动调用该方法。

void warp_mouse(position: Vector2) 🔗

将鼠标光标移动到 position，相对于该 Control 的 position。

注意：warp_mouse 仅在 Windows、macOS 和 Linux 上受支持。它在 Android、iOS 和 Web 上没有效果。