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...

键盘/控制器导航和焦点

对于用户界面来说，能够完全支持使用键盘和手柄进行导航与交互，是一项非常普遍的需求。这主要有两大好处：一是提升了无障碍体验（毕竟并不是所有人都能方便地使用鼠标或触屏来操作）；二是能让你的项目为登陆主机平台做好准备（或者，仅仅是为了照顾那些在 PC 上玩游戏时也更喜欢用手柄的玩家）。

使用键盘或控制器在 UI 元素之间导航是通过更改主动选择的节点来完成的。这也称为更改 UI 焦点。 Godot 中的每个 Control 节点都能够获得焦点。默认情况下，一些控件节点有能力自动拾取焦点内置的 UI 动作，并做出反应，例如 ui_up, ui_down, ui_focus_next 等。这些动作可以在项目的输入映射中的设置和修改。

警告

因为这些动作用于焦点，它们不应该被用于游戏代码。

节点设置

除了内置的逻辑之外，你还可以为每个单独的控件节点定义所谓的邻焦点。这允许在你项目的用户界面上的路径微调UI焦点。单个节点的设置可以在检查器栏的 "Control" 部分的 "Focus " 类别下找到。

邻近选项用于定义四向导航的节点，例如使用箭头键或控制器上的方向键。如，当使用向下箭头向下导航或按下方向键时，将使用底部邻近。 “下一个”和“上一个”选项与焦点转移按钮一起使用，例如桌面操作系统上的 Tab。

备注

如果节点被隐藏，它就会失去焦点。

模式设置定义了节点如何被聚焦。All意味着节点可以通过用鼠标点击，或用键盘或控制器选择而被关注。Click意味着只能通过点击来关注。最后，None意味着它根本不能被关注。不同的控件节点根据它们的典型使用方式有不同的默认设置，如，Label 节点默认设置为“None”，而按钮则为“All”。

确保为焦点和导航正确配置场景。如果节点没有配置邻焦点，引擎将尝试自动猜测下一个控件。这可能会导致意外行为，尤其是在没有明确定义垂直或水平导航操作的复杂用户界面中。

必要的代码

为了使键盘和控制器导航正常工作，在场景开始时，所有节点都需要使用代码进行焦点控制。如果不这样做，按下按钮或按键时，就不会有任何作用。

你可以使用 Control.grab_focus() 方法来让一个控件获得焦点。下面是一个通过代码设置初始焦点的基础示例：

GDScriptC#

func _ready():
    $StartButton.grab_focus.call_deferred()

这样一来，当场景开始运行时， "Start Button（开始按钮）" 节点就会自动获得焦点，玩家就可以直接用键盘或游戏手柄，在这个按钮和其他 UI 元素之间来回切换导航啦。