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