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”。

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

必要的代码

For keyboard and controller navigation to work correctly, any node must be focused by using code when the scene starts. Without doing this, pressing buttons or keys won't do anything.

You can use the Control.grab_focus() method to focus a control. Here is a basic example of setting initial focus with code:

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

public override void _Ready()
{
    GetNode<Button>("StartButton").GrabFocus.CallDeferred();
}

Now when the scene starts, the "Start Button" node will be focused, and the keyboard or a controller can be used to navigate between it and other UI elements.