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

鍵盤／控制器導覽與焦點

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

使用鍵盤或控制器在 UI 元素間切換，是透過更改目前被選取的節點，也就是切換 UI 焦點。Godot 中每個 Control 節點都可以取得焦點。預設情況下，部分控制元件會根據內建 UI 動作（如 ui_up、ui_down、ui_focus_next 等）自動取得焦點。這些動作可在專案設定的輸入映射中查看與調整。

警告

這些動作專用於焦點控制，不應用於遊戲玩法相關的程式碼。

節點設定

除了內建的焦點切換邏輯外，你還可以為每個控制元件自訂「鄰近焦點」。這能讓你精確調整 UI 焦點在介面中的移動路徑。各個節點的設定可以在屬性面板的「Control」區塊下「Focus」分類中找到。

鄰近選項用來定義四向導覽時的節點，例如使用鍵盤方向鍵或控制器的十字鍵。舉例來說，往下導覽時（按下方向鍵下或十字鍵下），會移動到下方鄰近節點。「下一個」與「上一個」則搭配焦點切換按鍵使用，例如桌面作業系統上的 Tab。

備註

若節點被隱藏，將會失去焦點。

模式設定決定節點可如何取得焦點。All 代表可以被滑鼠點擊，或用鍵盤／控制器選取以取得焦點。Click 則僅能透過滑鼠點擊取得焦點。None 則完全無法取得焦點。不同控制元件根據其用途會有不同預設值，例如 Label 預設為「None」，而 按鈕 預設為「All」。

請務必正確設定場景中的焦點與導覽。如果節點未設定鄰近焦點，Godot 會自動嘗試推測下一個控制元件，這可能導致非預期行為，尤其是在沒有明確垂直或水平導覽結構的複雜 UI 介面中。

必要程式碼

要讓鍵盤與控制器導覽正常運作，場景啟動時必須用程式碼將某個節點設為焦點。否則按下按鍵或按鈕不會有任何效果。

你可以使用 Control.grab_focus() 方法讓控制項取得焦點。以下是用程式碼設定初始焦點的基本範例：

GDScriptC#

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

現在，當場景啟動時，"Start Button" 節點會取得焦點，並可使用鍵盤或控制器在它與其他 UI 元素間導覽。