Input¶
继承： Object
用于处理输入的单例。
描述¶
Input单例处理按键、鼠标按钮和移动、应用手柄和输入操作。操作及其事件可以在Project>Project Settings的Input Map选项卡中设置，也可以使用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
工字形光标。通常用于显示单击鼠标时文本光标将出现的位置。
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之间，代表给定动作的强度。
注意：此方法不会引起任何Item.OnInput()调用，旨在与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 🔗
在使用应用手柄重新映射的平台上返回与SDL2兼容的设备GUID，例如030000004c050000c405000000010000。如果找不到，则返回空字符串。i3D使用SDL2应用控制器数据库根据此GUID确定应用手柄名称和映射。
在Windows上，所有XInput手柄GUID都将被i3D覆盖到__XINPUT_DEVICE__，因为它们的映射是相同的。
Dictionary get_joy_info(device: int) const 🔗
返回包含有关设备的额外平台特定信息的字典，例如操作系统中的原始应用手柄名称或Steam输入索引。
在Windows上，字典包含以下字段：
xinput_index：XInput系统中控制器的索引。DirectInput设备未定义。
vendor_id：设备的USB供应商ID。
product_id：设备的USB产品ID。
关于Linux：
raw_name：在被i3d控制器数据库重命名之前，控制器的名称来自操作系统。
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。i3D使用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，即使按下了操作的其中一个键。
注意：在输入处理期间（例如Item.OnInput()），使用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事件的方向。
注意：在输入处理期间（例如Item.OnInput()），使用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 🔗
如果您按下手柄按钮，则返回true（请参阅JoyButton）。
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键US QWERTY键盘上的物理位置按下该键，则返回true。您可以传递一个Key常量。
is_physical_key_pressed()比is_key_pressed()更适用于应用内的动作，因为无论用户的键盘布局如何，它都会使W/A/SD`布局工作。is_physical_key_pressed()还将确保顶部行号键适用于任何键盘布局。如果有疑问，请使用is_physical_key_pressed()。
注意：由于键盘重影，is_physical_key_pressed()可能会返回false，即使按下了操作的其中一个键。有关详细信息，请参阅文档中的输入示例。
void parse_input_event(event: InputEvent) 🔗
向应用提供一个InputEvent。可以用于从代码中手动触发输入事件。同时也会生成Item.OnInput()的调用。
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上，i3D将映射到内部回退映射。
void set_accelerometer(value: Vector3) 🔗
设置加速度计传感器的加速度值。可用于在没有硬件传感器的设备上进行调试，例如在PC上的编辑器中。
注意：此值可以立即被Android和iOS上的硬件传感器值覆盖。
void set_custom_mouse_cursor(image: Resource, shape: CursorShape = 0, hotspot: Vector2 = Vector2(0, 0)) 🔗
设置自定义鼠标光标图像，该图像仅在应用程序窗口内可见。也可以指定热点。将null传递给图像参数会重置为系统光标。有关形状列表，请参阅CursorShape。
image可以是Texture2D或Image，其大小必须小于或等于256×256。为避免渲染问题，建议使用小于或等于128×128的大小。
hotspot必须在image的大小内。
注意：AnimatedTextures不支持作为自定义鼠标光标。如果使用AnimatedTexture，只会显示第一帧。
注意：推荐使用无损、有损或未压缩压缩模式。可以使用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文档了解更多信息。
注意：一些第3方工具可以为忽略设备列表做出贡献。例如，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，仅在iOS13及更高版本中支持指定持续时间。
注意：对于Web，幅度不能改变。
注意：某些Web浏览器，如Safari和Firefox for Android不支持vibrate_handheld()。
void warp_mouse(position: Vector2) 🔗
将鼠标位置设置为指定向量，以像素为单位并相对于当前聚焦的窗口管理器应用程序窗口左上角的原点提供。
如果MouseMode设置为MOUSE_MODE_CONFINED或MOUSE_MODE_CONFINED_HIDDEN，则鼠标位置被裁剪到屏幕分辨率的限制，或应用程序窗口的限制。
注意：warp_mouse()仅在Windows、macOS和Linux上受支持，对Android、iOS和Web没有影响。