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...
Input
继承： Object
用于处理输入的单例。
描述
Input 是处理键盘按键、鼠标按钮及移动、游戏手柄、输入动作等的单例。动作以及对应的事件可以在项目 > 项目设置的输入映射选项卡中设置，也可以使用 InputMap 类设置。
注意：Input 的方法反映的是全局输入状态，不受 Control.accept_event() 和 Viewport.set_input_as_handled() 的影响，因为这两个方法处理的是输入在 SceneTree 中传播的方式。
教程
属性
方法
信号
joy_connection_changed(device: int, connected: bool) 🔗
连接或断开游戏手柄设备时触发。
枚举
enum MouseMode: 🔗
MouseMode MOUSE_MODE_VISIBLE = 0
如果鼠标光标处于隐藏状态，则使其可见。
如果鼠标光标是可见的，则使其隐藏。
MouseMode MOUSE_MODE_CAPTURED = 2
捕获鼠标。鼠标将被隐藏，其位置被锁定在窗口管理器窗口的中心。
注意：如果你想在这种模式下处理鼠标的移动，则需要使用 InputEventMouseMotion.relative。
MouseMode MOUSE_MODE_CONFINED = 3
将鼠标光标限制在游戏窗口内，并使其可见。
将鼠标光标限制在游戏窗口内，并使其隐藏。
MouseMode MOUSE_MODE_MAX = 5
MouseMode 的最大值。
enum CursorShape: 🔗
CursorShape CURSOR_ARROW = 0
箭头光标。标准，默认指向光标。
CursorShape CURSOR_IBEAM = 1
I 形光标。通常用于指示点击鼠标后文本光标的位置。
CursorShape CURSOR_POINTING_HAND = 2
指向手形光标。通常用在指示链接或其他可交互项上。
CursorShape CURSOR_CROSS = 3
十字光标。通常出现在可以执行绘制操作或进行选择的区域上方。
CursorShape CURSOR_WAIT = 4
等待光标。表示应用程序正忙于执行某项操作，并且它在操作期间无法使用（例如，某些东西正在阻塞其主线程）。
CursorShape CURSOR_BUSY = 5
忙碌光标。表示应用程序正忙于执行某项操作，并且它在操作期间仍然可用。
CursorShape CURSOR_DRAG = 6
拖动光标。通常在拖动某物时显示。
注意：Windows 上没有拖动光标，因此 CURSOR_DRAG 与该平台的 CURSOR_MOVE 相同。
CursorShape CURSOR_CAN_DROP = 7
可以放下的光标。通常在拖动东西时显示，表示可以在当前位置放下。
CursorShape CURSOR_FORBIDDEN = 8
禁止的光标。表示当前操作是被禁止的（例如，拖动东西时）或某个位置的控件被禁用。
CursorShape CURSOR_VSIZE = 9
垂直调整大小的光标。一个双头的垂直箭头。它告诉用户他们可以垂直地调整窗口或面板的大小。
CursorShape CURSOR_HSIZE = 10
水平调整尺寸的光标。一个双头的水平箭头。它告诉用户他们可以水平调整窗口或面板的大小。
CursorShape CURSOR_BDIAGSIZE = 11
窗口调整大小的光标。该光标是一个双头箭头，从左下方到右上方。它告诉用户他们可以在水平和垂直方向上调整窗口或面板的大小。
CursorShape CURSOR_FDIAGSIZE = 12
窗口调整大小的光标。是一个双头的箭头，从左上角到右下角，与 CURSOR_BDIAGSIZE 相反。它告诉用户他们可以在水平和垂直方向上调整窗口或面板的大小。
CursorShape CURSOR_MOVE = 13
移动光标。表示那些东西可以移动。
CursorShape CURSOR_VSPLIT = 14
垂直拆分鼠标光标。在 Windows 上与 CURSOR_VSIZE 相同。
CursorShape CURSOR_HSPLIT = 15
水平分割的鼠标光标。在 Windows 上与 CURSOR_HSIZE 相同。
CursorShape CURSOR_HELP = 16
帮助光标。通常是一个问号。
属性说明
bool emulate_mouse_from_touch 🔗
如果为 true，则在点击或滑动触摸屏时发送鼠标输入事件。另见 ProjectSettings.input_devices/pointing/emulate_mouse_from_touch。
bool emulate_touch_from_mouse 🔗
如果为 true，则在点击或拖动鼠标时发送触摸输入事件。另见 ProjectSettings.input_devices/pointing/emulate_touch_from_mouse。
控制鼠标模式。详见 MouseMode。
如果为 true，则操作系统发送的相似输入事件将被累积。当输入累积被启用时，在帧期间内所有生成的输入事件，将在帧完成渲染时被合并并发出。因此，这会将每秒输入方法被调用的数量限制为渲染 FPS。
输入累积可以被禁用，以增加 CPU 使用率为代价，获得稍微更具精确性/反应性的输入。在需要徒手绘制线条的应用程序中，输入累积通常应在用户绘制线条时被禁用，以获得与实际输入非常接近的结果。
注意：输入累积默认是启用的 。
方法说明
void action_press(action: StringName, strength: float = 1.0) 🔗
这将模拟按下指定的按键动作。
强度可以用于非布尔运算的动作，它的范围在 0 到 1 之间，代表给定动作的力度。
注意：这个方法不会引起任何 Node._input() 调用。它旨在与 is_action_pressed() 和 is_action_just_pressed() 一起使用。如果你想模拟 _input，请使用 parse_input_event() 代替。
void action_release(action: StringName) 🔗
如果已按下指定操作，那么将释放它。
void add_joy_mapping(mapping: String, update_existing: bool = false) 🔗
在映射数据库中添加新的映射条目（SDL2 格式）。可选更新已连接的设备。
void flush_buffered_events() 🔗
将当前缓冲区内的所有输入事件发送给游戏循环。这些事件可能是由于累积输入（use_accumulated_input）或敏捷输入刷新（ProjectSettings.input_devices/buffering/agile_event_flushing）而被缓冲的结果。
引擎已经会在关键的执行点执行此操作，至少每帧一次。然而，在你想要精确控制事件处理时间的高级情况下，这可能是有用的。
Vector3 get_accelerometer() const 🔗
如果设备有加速度计传感器，则返回该设备加速度计传感器的加速度，单位为 m/s²。否则，该方法返回 Vector3.ZERO。
请注意，即使你的设备具有一个加速度计，在从编辑器运行时，该方法也会返回一个空的 Vector3。必须将项目导出到一个支持的设备上，才能从加速度计读取值。
注意：该方法仅适用于 Android 和 iOS。在其他平台上，它总是返回 Vector3.ZERO。
注意：在 Android 上必须启用 ProjectSettings.input_devices/sensors/enable_accelerometer。
float get_action_raw_strength(action: StringName, exact_match: bool = false) const 🔗
返回一个介于 0 和 1 之间的值，表示给定动作的原始强度，忽略动作的死区。在大多数情况下，应该改用 get_action_strength()。
如果 exact_match 为 false，它会忽略 InputEventKey 和 InputEventMouseButton 事件的额外输入修饰键，以及 InputEventJoypadMotion 事件的方向。
float get_action_strength(action: StringName, exact_match: bool = false) const 🔗
返回一个介于 0 和 1 之间的值，表示给定动作的强度。例如，在游戏手柄中，轴（模拟摇杆或 L2、R2 触发器）离死区越远，该值将越接近 1。如果动作被映射到一个如键盘一样没有轴的控制器时，返回值将为 0 或 1。
如果 exact_match 为 false，它会忽略 InputEventKey 和 InputEventMouseButton 事件的额外输入修饰键，以及 InputEventJoypadMotion 事件的方向。
float get_axis(negative_action: StringName, positive_action: StringName) const 🔗
通过指定两个动作来获取轴的输入，一个是负的，一个是正的。
这是 Input.get_action_strength("positive_action")-Input.get_action_strength("negative_action") 的简写。
Array[int] get_connected_joypads() 🔗
返回一个 Array，包含当前所有连接手柄的设备 ID。
CursorShape get_current_cursor_shape() const 🔗
返回当前指定的光标形状（见 CursorShape）。
如果设备有加速度计传感器，则返回该设备有加速度计传感器的重力，单位为 m/s²。否则，该方法返回 Vector3.ZERO。
注意：该方法仅适用于 Android 和 iOS。在其他平台上，它总是返回 Vector3.ZERO。
注意：在 Android 上必须启用 ProjectSettings.input_devices/sensors/enable_gravity。
Vector3 get_gyroscope() const 🔗
如果设备有陀螺仪传感器，则返回围绕设备 X、Y、Z 轴的旋转速率，单位为 rad/s。否则，该方法返回 Vector3.ZERO。
注意：这个方法只在 Android 和 iOS 上工作。在其他平台上，总是返回 Vector3.ZERO。
注意：在 Android 上必须启用 ProjectSettings.input_devices/sensors/enable_gyroscope。
float get_joy_axis(device: int, axis: JoyAxis) const 🔗
返回给定索引（参见 JoyAxis）处的游戏手柄轴的当前值。
String get_joy_guid(device: int) const 🔗
如果平台使用游戏手柄重映射，则返回设备的 GUID，与 SDL2 兼容，例如 030000004c050000c405000000010000。如果无法找到则返回空字符串。Godot 会根据这个 GUID 使用 SDL2 游戏控制器数据库来确定游戏手柄的名称和映射。
在 Windows 上，Godot 会将所有 XInput 游戏手柄的 GUID 覆盖为 __XINPUT_DEVICE__，因为它们的映射是相同的。
Dictionary get_joy_info(device: int) const 🔗
返回关于设备的额外平台相关信息字典，例如操作系统的原始游戏手柄名称，或者 Steam Input 索引。
在 Windows 上，该字典包含如下字段：
xinput_index：控制器在 XInput 系统中的索引。如果是 DirectInput 设备则未定义。
vendor_id：设备的 USB 供应商 ID。
product_id：设备的 USB 产品 ID。
在 Linux 上：
raw_name：从操作系统获取的控制器名称，未经 Godot 控制器数据库重命名。
vendor_id：设备的 USB 供应商 ID。
product_id：设备的 USB 产品 ID。
steam_input_index：Steam Input 游戏手柄索引，如果该设备不是 Steam Input 设备则该字段不存在。
注意：在 Web、iOS、Android 和 macOS 平台上，返回的字典始终为空。
String get_joy_name(device: int) 🔗
返回位于指定设备索引的游戏手柄名称，例如 PS4 Controller。Godot 使用 SDL2 游戏控制器数据库来确定游戏手柄的名称。
float get_joy_vibration_duration(device: int) 🔗
以秒为单位返回当前振动效果的持续时间。
Vector2 get_joy_vibration_strength(device: int) 🔗
返回手柄振动的强度：x 是弱马达的强度，y 是强马达的强度。
Vector2 get_last_mouse_screen_velocity() 🔗
返回屏幕坐标中上次的鼠标速度。为了提供精确且无抖动的速度，鼠标速度仅每 0.1 秒计算一次。因此，鼠标速度将滞后于鼠标移动。
Vector2 get_last_mouse_velocity() 🔗
返回上次的鼠标速度。为了提供精确且无抖动的速度，鼠标速度仅每 0.1 秒计算一次。因此，鼠标速度将滞后于鼠标移动。
Vector3 get_magnetometer() const 🔗
如果设备有磁力传感器，则返回设备所有轴的磁场强度，单位为微特斯拉。否则，该方法返回 Vector3.ZERO。
注意：该方法仅适用于 Android 和 iOS。在其他平台上，它总是返回 Vector3.ZERO。
注意：在 Android 上必须启用 ProjectSettings.input_devices/sensors/enable_magnetometer。
BitField[MouseButtonMask] get_mouse_button_mask() const 🔗
将鼠标按键作为一个位掩码返回。如果多个鼠标按钮同时被按下，则这些位将被加在一起。相当于 DisplayServer.mouse_get_button_state()。
Vector2 get_vector(negative_x: StringName, positive_x: StringName, negative_y: StringName, positive_y: StringName, deadzone: float = -1.0) const 🔗
通过指定正负 X 和 Y 轴的四个动作来获取输入向量。
这个方法在获取向量输入时很有用，比如从操纵杆、方向盘、箭头或 WASD。向量的长度被限制为 1，并且有一个圆形的死区，这对于使用向量输入进行运动很有用。
默认情况下，死区根据动作死区的平均值自动计算。然而，你可以把死区覆盖为任何你想要的值（在 0 到 1 的范围内）。
bool is_action_just_pressed(action: StringName, exact_match: bool = false) const 🔗
当用户在当前帧或物理周期中开始按下动作事件时返回 true。只在用户按下按钮的那一帧或周期中为 true。
如果代码只需要在动作按下时执行一次，而不是只要处于按下状态就每帧都需要执行，那么这个方法就很有用。
如果 exact_match 为 false，则会忽略 InputEventKey 和 InputEventMouseButton 事件的额外输入修饰键，以及 InputEventJoypadMotion 事件的方向。
注意：返回 true 并不意味着该动作仍然处于按下状态。动作在按下后是可以很快再释放的，为了不丢失输入，这种情况下仍然会返回 true。
注意：由于键盘重影，即便该动作的某个键处于按下状态，is_action_just_pressed() 仍可能会返回 false。详见文档中的《输入示例》。
注意：在输入处理期间（例如 Node._input()），请使用 InputEvent.is_action_pressed() 来查询当前事件的动作状态。
bool is_action_just_released(action: StringName, exact_match: bool = false) const 🔗
当用户在当前帧或物理周期中停止按下动作事件时返回 true。只在用户松开按钮的那一帧或周期中为 true。
注意：返回 true 并不意味着该动作仍然处于松开状态。动作在松开后是可以很快再按下的，为了不丢失输入，这种情况下仍然会返回 true。
如果 exact_match 为 false，则会忽略 InputEventKey 和 InputEventMouseButton 事件的额外输入修饰键，以及 InputEventJoypadMotion 事件的方向。
注意：在输入处理期间（例如 Node._input()），请使用 InputEvent.is_action_released() 来查询当前事件的动作状态。
bool is_action_pressed(action: StringName, exact_match: bool = false) const 🔗
如果正在按下操作事件，则返回 true。
如果 exact_match 为 false，则它会忽略 InputEventKey 和 InputEventMouseButton 事件的额外输入修饰键，以及 InputEventJoypadMotion 事件的方向。
注意：由于键盘重影，is_action_pressed() 可能会返回 false，即使动作的某个键被按下时也是如此。有关详细信息，请参阅文档中的 《输入示例》。
bool is_anything_pressed() const 🔗
如果任何动作、按键、游戏手柄按钮或鼠标按钮正被按下，则返回 true。如果动作是通过调用 action_press() 以通过代码来模拟，该方法也将返回 true。
bool is_joy_button_pressed(device: int, button: JoyButton) const 🔗
如果游戏手柄按钮（参见 JoyButton）正被按下，则返回 true。
bool is_joy_known(device: int) 🔗
如果系统知道指定的设备，则返回 true。这意味着它设置了所有按钮和轴索引。未知的游戏手柄预计不会匹配这些常量，但仍然可以从中检索事件。
bool is_key_label_pressed(keycode: Key) const 🔗
如果正按下印有 keycode 的键，则返回 true。可以传递一个 Key 常量或任何 Unicode 字符代码。
bool is_key_pressed(keycode: Key) const 🔗
如果在当前键盘布局中正在按该拉丁键，则返回 true。可以传递一个 Key 常量。
只有在非游戏应用程序中，才推荐使用 is_key_pressed() 而不是 is_physical_key_pressed()。这可确保快捷键将根据用户的键盘布局按预期运行，因为在非游戏应用程序中，键盘快捷键通常取决于键盘布局。如有疑问，请使用 is_physical_key_pressed()。
注意：由于键盘重影，即使按下动作的某个键，is_key_pressed() 也有可能会返回 false。有关详细信息，请参阅文档中的《输入示例》。
bool is_mouse_button_pressed(button: MouseButton) const 🔗
如果正在按下由 MouseButton 指定的鼠标按钮，则返回 true。
bool is_physical_key_pressed(keycode: Key) const 🔗
如果正按下 101/102 键美式 QWERTY 键盘物理位置上的键，则返回 true。可以传递一个 Key 常量。
与 is_key_pressed() 相比，is_physical_key_pressed() 被推荐用于游戏内的动作，因为无论用户的键盘布局如何，它都会使 W/A/S/D 布局有效。is_physical_key_pressed() 还将确保顶行数字键在任何键盘布局上有效。如有疑问，请使用 is_physical_key_pressed()。
注意：由于键盘重影，即使按下动作的某个键，is_physical_key_pressed() 也有可能会返回 false。有关详细信息，请参阅文档中的《输入示例》。
void parse_input_event(event: InputEvent) 🔗
向游戏提供一个 InputEvent。可用于通过代码人为地触发输入事件。也会产生 Node._input() 调用。
var cancel_event = InputEventAction.new()
cancel_event.action = "ui_cancel"
cancel_event.pressed = true
Input.parse_input_event(cancel_event)
var cancelEvent = new InputEventAction();
cancelEvent.Action = "ui_cancel";
cancelEvent.Pressed = true;
Input.ParseInputEvent(cancelEvent);
注意：调用该函数不会影响操作系统。因此，发送 InputEventMouseMotion 事件并不会将操作系统的鼠标光标移动到指定位置（请改用 warp_mouse()），发送 Alt/Cmd + Tab 对应的 InputEventKey 也不会触发当前窗口的切换。
void remove_joy_mapping(guid: String) 🔗
在内部数据库中移除所有与给定 GUID 匹配的映射。所有当前连接的使用该 GUID 的游戏手柄将变为未映射状态。
在 Android 上，Godot 将映射到一个内部的回退映射。
void set_accelerometer(value: Vector3) 🔗
设置加速度传感器的加速度值。可以用于在没有硬件传感器的设备上进行调试，例如在 PC 上的编辑器中。
注意：这个值在 Android 和 iOS 上可立即被硬件传感器的值所覆盖。
void set_custom_mouse_cursor(image: Resource, shape: CursorShape = 0, hotspot: Vector2 = Vector2(0, 0)) 🔗
设置自定义鼠标光标图像，该图像仅在游戏窗口内可见。还可以指定热点。将 null 传递给 image 参数将重置为系统光标。形状列表见 CursorShape。
image 可以是 Texture2D 或 Image，其大小必须小于等于 256×256。为了避免渲染问题，建议使用小于等于 128×128 的大小。
hotspot 必须在 image 的大小范围内。
注意：不支持使用 AnimatedTexture 作为自定义鼠标光标。如果使用 AnimatedTexture，则只会显示第一帧。
注意：推荐使用 Lossless、Lossy 或 Uncompressed 压缩模式。Video RAM 压缩模式也可以，但会使用 CPU 解压，拖慢加载，相对于无损模式也并不节省内存。
注意：在网络平台上，光标图像允许的最大尺寸为 128×128。 出于安全原因，只有当鼠标光标图像完全位于页面内时，大于 32×32 的光标图像才会显示。
void set_default_cursor_shape(shape: CursorShape = 0) 🔗
设置该视口中使用的默认光标形状，而不是 CURSOR_ARROW。
注意：如果要更改 Control 节点的默认光标形状，请改用 Control.mouse_default_cursor_shape。
注意：这个方法会生成一个 InputEventMouseMotion 以立即更新光标。
void set_gravity(value: Vector3) 🔗
设置加速度传感器的重力值。可用于在没有硬件传感器的设备上进行调试，例如在 PC 上的编辑器中。
注意：这个值在 Android 和 iOS 上可立即被硬件传感器的值覆盖。
void set_gyroscope(value: Vector3) 🔗
设置陀螺仪传感器的旋转速率值。可用于在没有硬件传感器的设备上进行调试，例如在 PC 上的编辑器中。
注意：在 Android 和 iOS 上，这个值可立即被硬件传感器的值所覆盖。
void set_magnetometer(value: Vector3) 🔗
设置磁力传感器的磁场值。可用于在没有硬件传感器的设备上进行调试，例如在 PC 上的编辑器中。
注意：在 Android 和 iOS 上，这个值可立即被硬件传感器的值所覆盖。
bool should_ignore_device(vendor_id: int, product_id: int) const 🔗
查询输入设备是否应被忽略。可以通过设置环境变量 SDL_GAMECONTROLLER_IGNORE_DEVICES 来忽略设备。请阅读 SDL 文档了解更多信息。
注意：某些第三方工具可以添加忽略设备列表。例如，SteamInput 从物理设备创建虚拟设备以进行重新映射。为了避免两次处理相同的输入设备，原始设备被添加到忽略列表中。
void start_joy_vibration(device: int, weak_magnitude: float, strong_magnitude: float, duration: float = 0) 🔗
开始振动游戏手柄。游戏手柄通常带有两个震动马达，一强一弱。weak_magnitude 是弱马达的强度（介于 0 和 1 之间），strong_magnitude 是强马达的强度（介于 0 和 1 之间）。duration 是效果的持续时间（以秒为单位）（持续时间为 0 将尝试无限期地播放振动）。调用 stop_joy_vibration() 可以提前停止震动。
注意：并非所有硬件都兼容长效果持续时间；如果播放的时长必须超过几秒钟，建议重新启动效果。
注意：对于 macOS，仅 macOS 11 及更高版本支持振动。
void stop_joy_vibration(device: int) 🔗
停止使用 start_joy_vibration() 启动的游戏手柄的振动。
void vibrate_handheld(duration_ms: int = 500, amplitude: float = -1.0) 🔗
使手持设备振动指定的持续时间，单位为毫秒。
amplitude 是振动的强度，取值范围为 0.0 为 1.0 之间。如果设为 -1.0 则表示该设备的默认振动强度。
注意：该方法在 Android、iOS 和 Web 上实现。在其他平台上无效。
注意：在 Android 平台上，vibrate_handheld() 需要在导出预设中启用 VIBRATE 权限。否则 vibrate_handheld() 无效。
注意：在 iOS 平台上，仅 iOS 13 及更高版本支持指定持续时间。
注意：在 Web 平台上，振幅无法修改。
注意：部分浏览器不支持 vibrate_handheld()，如 Android 版的 Safari、Firefox 等。
void warp_mouse(position: Vector2) 🔗
将鼠标位置设置为指定的向量，单位为像素，并相对于当前聚焦的窗口管理器游戏窗口左上角的原点。
如果 MouseMode 被设置为 MOUSE_MODE_CONFINED 或 MOUSE_MODE_CONFINED_HIDDEN，则鼠标位置会被钳制在屏幕分辨率的限制内，或者钳制在游戏窗口的限制内。
注意：warp_mouse() 仅支持 Windows、macOS 和 Linux。它对 Android、iOS 和 Web 没有影响。