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

Tastatur/Controller-Navigation und Fokus

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

Das Navigieren zwischen UI-Elementen mit der Tastatur oder dem Controller erfolgt, indem der aktiv ausgewählte Node geändert wird. Dies wird auch als Änderung des UI-Fokus bezeichnet. Jeder Control-Node in Godot ist in der Lage, den Fokus zu haben. Standardmäßig haben einige Control-Nodes die Fähigkeit, automatisch den Fokus zu erhalten, indem sie auf Built-in-UI-Aktionen wie ui_up, ui_down, ui_focus_next usw. reagieren. Diese Aktionen sind in den Projekteinstellungen in der Input Map zu sehen und können geändert werden.

Warnung

Da diese Aktionen für den Fokus verwendet werden, sollten sie nicht für Gameplay-Code verwendet werden.

Node-Einstellungen

Zusätzlich zur Built-in-Logik können Sie für jeden einzelnen Control-Node so genannte Fokus-Nachbarn definieren. Damit können Sie den Pfad, den der UI-Fokus über die Benutzeroberfläche Ihres Projekts nimmt, fein abstimmen. Die Einstellungen für einzelne Nodes finden Sie im Inspektor-Dock unter der Kategorie "Fokus" im Abschnitt "Control".

Nachbaroptionen werden verwendet, um Nodes für die Navigation in 4 Richtungen zu definieren, z.B. mit Pfeiltasten oder einem D-Pad auf einem Controller. Der untere Nachbar wird z.B. verwendet, wenn mit dem Pfeil nach unten oder durch Drücken des D-Pads nach unten navigiert wird. Die Optionen "Weiter" und "Zurück" werden mit der Fokus-Wechseltaste verwendet, z.B. Tab auf Desktop-Betriebssystemen.

Bemerkung

Ein Node kann den Fokus verlieren, wenn er ausgeblendet wird.

Die Moduseinstellung legt fest, wie ein Node fokussiert werden kann. Alle bedeutet, dass ein Node durch Anklicken mit der Maus oder durch Auswahl mit einer Tastatur oder einem Control fokussiert werden kann. Klick bedeutet, dass er nur durch Anklicken fokussiert werden kann. Schließlich bedeutet Keine, dass er überhaupt nicht fokussiert werden kann. Verschiedene Control-Nodes haben unterschiedliche Defaulteinstellungen, je nachdem, wie sie typischerweise verwendet werden. Zum Beispiel sind Label-Nodes standardmäßig auf "None" gesetzt, während Buttons auf "All" gesetzt sind.

Stellen Sie sicher, dass Sie Ihre Szenen für Fokus und Navigation richtig konfigurieren. Wenn für einen Node kein Fokus-Nachbar konfiguriert ist, versucht die Engine, das nächste Control automatisch zu erraten. Dies kann zu unbeabsichtigtem Verhalten führen, insbesondere bei einer komplexen Benutzeroberfläche, die keinen klar definierten vertikalen oder horizontalen Navigationsfluss aufweist.

Erforderlicher Code

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:

GDScriptC#

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

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.