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.

键盘/控制器导航和焦点

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

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

警告

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

节点设置

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

../../_images/focus_settings.png

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

备注

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

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

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

必要的代码

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

func _ready():
    $StartButton.grab_focus()

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