Keyboard/Controller Navigation и Focus

It is a common requirement for a user interface to have full keyboard and controller support for navigation and interaction. There are two main reasons why this is beneficial for projects: improved accessibility (not everyone can use mouse or touch controls for interactions), and getting your project ready for consoles (or just for people who prefer to game with a controller on PC).

Навигация между элементами пользовательского интерфейса с помощью клавиатуры или контроллера осуществляется путём смены активного выбранного узла. Это также называется сменой фокуса пользовательского интерфейса. Каждый узел Control в Godot может иметь фокус. По умолчанию некоторые узлы управления автоматически захватывают фокус, реагируя на встроенные действия пользовательского интерфейса, такие как ui_up, ui_down, ui_focus_next и т. д. Эти действия можно увидеть в настройках проекта на карте входных данных и изменить.

Предупреждение

Поскольку эти действия используются для фокусировки, их не следует использовать для какого-либо игрового кода.

Настройки узла

Помимо встроенной логики, вы можете определить так называемых соседей фокуса для каждого отдельного узла управления. Это позволяет точно настроить путь фокуса пользовательского интерфейса в пользовательском интерфейсе вашего проекта. Настройки для отдельных узлов можно найти в панели инспектора, в категории "Focus" раздела "Control".

Параметры "Neighbor" используются для определения узлов для навигации в четырёх направлениях, например, с помощью клавиш со стрелками или крестовины на контроллере. Например, нижний сосед будет использоваться при навигации вниз с помощью стрелки вниз или нажатия на крестовине. Параметры "Next" и "Previous" используются с кнопкой переключения фокуса, например, Tab в настольных операционных системах.

Примечание

Узел может потерять фокус, если он станет скрытым.

Настройка режима определяет, как узел может быть сфокусирован. All означает, что узел можно сфокусировать, щёлкнув по нему мышью или выбрав его с помощью клавиатуры или контроллера. Click означает, что узел может быть сфокусирован только щелчком мыши. Наконец, None означает, что узел вообще не может быть сфокусирован. Различные узлы управления имеют различные настройки по умолчанию в зависимости от того, как они обычно используются, например, узлы Label по умолчанию имеют значение "None", а узлы buttons имеют значение "All".

Убедитесь, что сцены правильно настроены для фокусировки и навигации. Если у узла не настроен соседний элемент фокусировки, движок попытается автоматически определить следующий элемент управления. Это может привести к непреднамеренному поведению, особенно в сложном пользовательском интерфейсе без четко выраженной вертикальной или горизонтальной навигации.

Необходимый код

Для корректной работы навигации с помощью клавиатуры и контроллера необходимо, чтобы любой узел был сфокусирован с помощью кода при запуске сцены. Без этого нажатие кнопок или клавиш не будет работать.

Для фокусировки элемента управления можно использовать метод Control.grab_focus(). Вот простой пример установки начального фокуса с помощью кода:

GDScriptC#

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

Теперь при запуске сцены узел "Start Button" будет в фокусе, и для навигации между ним и другими элементами пользовательского интерфейса можно будет использовать клавиатуру или контроллер.