键盘/控制器导航和焦点

对于用户界面来说，支持全键盘和控制器进行导航和交互是常见的。这有利于改善项目可访问性，不是每个人都能使用鼠标或触摸控制进行交互，或是让你的项目准备在 :ref:`consoles <doc_consoles>`运行，或者只是为了那些喜欢在PC上用控制器玩游戏的人。

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

警告

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

节点设置

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

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

注解

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

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

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

必要的代码

为了使键盘和控制器导航正常工作，在场景开始时，所有节点都需要使用代码进行焦点控制。如果不这样做，按下按钮或按键时，就不会有任何作用。下面是一个用代码设置初始焦点的基本例子:

GDScript

C#

func _ready():
    $StartButton.grab_focus()

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

现在，当场景启动，”Start Button” 节点被聚焦，键盘或控制器可以用来在它和其他UI元素之间进行导航。