Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Navegación por teclado/controlador y enfoque

Es un requisito común que una interfaz de usuario tenga soporte completo para navegación e interacción mediante teclado y controlador. Hay dos razones principales por las que esto es beneficioso para los proyectos: mejora la accesibilidad (no todas las personas pueden usar el mouse o controles táctiles para interactuar) y prepara tu proyecto para su uso en consolas (o simplemente para personas que prefieren jugar con un controlador en PC).

La navegación entre elementos de la interfaz de usuario con el teclado o el controlador se realiza cambiando qué nodo está seleccionado activamente. Esto también se conoce como cambiar el enfoque de la interfaz de usuario. Cada nodo Control en Godot es capaz de tener el enfoque. Por defecto, algunos nodos de control tienen la capacidad de obtener automáticamente el enfoque en respuesta a acciones de interfaz de usuario incorporadas, como ui_up, ui_down, ui_focus_next, etc. Estas acciones se pueden ver en la configuración del proyecto en el mapa de entrada y se pueden modificar.

Advertencia

Debido a que estas acciones se utilizan para el enfoque, no se deben utilizar para ningún código de jugabilidad.

Ajustes de nodo

Además de la lógica incorporada, puedes definir lo que se conoce como "focus neighbors" (vecinos de enfoque) para cada nodo de control individual. Esto te permite ajustar finamente la ruta que toma el enfoque de la interfaz de usuario en tu proyecto. La configuración para nodos individuales se puede encontrar en el panel del Inspector, dentro de la categoría "Focus" (Enfoque) de la sección "Control".

../../_images/focus_settings.png

Las opciones de vecinos se utilizan para definir nodos para la navegación en 4 direcciones, como el uso de las teclas de flecha o un D-pad en un controlador. Por ejemplo, el vecino inferior se utilizará al navegar hacia abajo con la flecha hacia abajo o al presionar hacia abajo en el D-pad. Las opciones "Next" (Siguiente) y "Previous" (Anterior) se utilizan con el botón de cambio de enfoque, como Tab en sistemas operativos de escritorio.

Nota

Un nodo puede perder el enfoque si se oculta.

El ajuste del modo define cómo un nodo puede recibir el enfoque. Todos significa que un nodo puede recibir el enfoque al hacer clic sobre él con el ratón, o al seleccionarlo con el teclado o el controlador. Clic significa que solo puede recibir el enfoque al hacer clic sobre él. Por último, Ninguno significa que no puede recibir el enfoque en absoluto. Diferentes nodos de control tienen diferentes ajustes predeterminados para esto basados en cómo se usan típicamente, por ejemplo, los nodos Label están configurados como "Ninguno" de forma predeterminada, mientras que los botones están configurados como "Todos".

Asegúrate de configurar correctamente tus escenas para el enfoque y la navegación. Si un nodo no tiene un vecino de enfoque configurado, el motor intentará adivinar el siguiente control automáticamente. Esto puede dar lugar a un comportamiento no deseado, especialmente en una interfaz de usuario compleja que no tiene un flujo de navegación vertical u horizontal bien definido.

Código necesario

Para que la navegación con el teclado y el controlador funcione correctamente, es necesario que cualquier nodo esté enfocado mediante código cuando la escena se inicie. Sin hacer esto, presionar botones o teclas no tendrá ningún efecto. Aquí tienes un ejemplo básico de cómo establecer el enfoque inicial mediante código:

func _ready():
    $StartButton.grab_focus()

Ahora, cuando la escena se inicie, el nodo "Start Button" estará enfocado, y se podrá utilizar el teclado o un controlador para navegar entre él y otros elementos de la interfaz de usuario.