mirror of
https://github.com/godotengine/godot-docs-l10n.git
synced 2025-12-31 09:49:22 +03:00
359 lines
17 KiB
ReStructuredText
359 lines
17 KiB
ReStructuredText
:github_url: hide
|
|
|
|
.. _class_InputEventKey:
|
|
|
|
InputEventKey
|
|
=============
|
|
|
|
**繼承：** :ref:`InputEventWithModifiers<class_InputEventWithModifiers>` **<** :ref:`InputEventFromWindow<class_InputEventFromWindow>` **<** :ref:`InputEvent<class_InputEvent>` **<** :ref:`Resource<class_Resource>` **<** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`
|
|
|
|
代表鍵盤上的某個按鍵被按下或鬆開。
|
|
|
|
.. rst-class:: classref-introduction-group
|
|
|
|
說明
|
|
----
|
|
|
|
鍵盤上的按鍵操作對應的輸入事件。支援按鍵按下、釋放和 :ref:`echo<class_InputEventKey_property_echo>` 事件。還可以在 :ref:`Node._unhandled_key_input()<class_Node_private_method__unhandled_key_input>` 收到。
|
|
|
|
\ **注意：**\ 從鍵盤上接收的事件通常設定了所有屬性。事件對應應該只設定 :ref:`keycode<class_InputEventKey_property_keycode>`\ 、\ :ref:`physical_keycode<class_InputEventKey_property_physical_keycode>`\ 、\ :ref:`unicode<class_InputEventKey_property_unicode>` 的其中之一。
|
|
|
|
比較事件時，將按以下優先順序檢查屬性——\ :ref:`keycode<class_InputEventKey_property_keycode>`\ 、\ :ref:`physical_keycode<class_InputEventKey_property_physical_keycode>`\ 、\ :ref:`unicode<class_InputEventKey_property_unicode>`\ 。有一個配對就會認為事件相等。
|
|
|
|
.. rst-class:: classref-introduction-group
|
|
|
|
教學
|
|
----
|
|
|
|
- :doc:`使用 InputEvent <../tutorials/inputs/inputevent>`
|
|
|
|
.. rst-class:: classref-reftable-group
|
|
|
|
屬性
|
|
----
|
|
|
|
.. table::
|
|
:widths: auto
|
|
|
|
+---------------------------------------------------+------------------------------------------------------------------------+-----------+
|
|
| :ref:`bool<class_bool>` | :ref:`echo<class_InputEventKey_property_echo>` | ``false`` |
|
|
+---------------------------------------------------+------------------------------------------------------------------------+-----------+
|
|
| :ref:`Key<enum_@GlobalScope_Key>` | :ref:`key_label<class_InputEventKey_property_key_label>` | ``0`` |
|
|
+---------------------------------------------------+------------------------------------------------------------------------+-----------+
|
|
| :ref:`Key<enum_@GlobalScope_Key>` | :ref:`keycode<class_InputEventKey_property_keycode>` | ``0`` |
|
|
+---------------------------------------------------+------------------------------------------------------------------------+-----------+
|
|
| :ref:`KeyLocation<enum_@GlobalScope_KeyLocation>` | :ref:`location<class_InputEventKey_property_location>` | ``0`` |
|
|
+---------------------------------------------------+------------------------------------------------------------------------+-----------+
|
|
| :ref:`Key<enum_@GlobalScope_Key>` | :ref:`physical_keycode<class_InputEventKey_property_physical_keycode>` | ``0`` |
|
|
+---------------------------------------------------+------------------------------------------------------------------------+-----------+
|
|
| :ref:`bool<class_bool>` | :ref:`pressed<class_InputEventKey_property_pressed>` | ``false`` |
|
|
+---------------------------------------------------+------------------------------------------------------------------------+-----------+
|
|
| :ref:`int<class_int>` | :ref:`unicode<class_InputEventKey_property_unicode>` | ``0`` |
|
|
+---------------------------------------------------+------------------------------------------------------------------------+-----------+
|
|
|
|
.. rst-class:: classref-reftable-group
|
|
|
|
方法
|
|
----
|
|
|
|
.. table::
|
|
:widths: auto
|
|
|
|
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`String<class_String>` | :ref:`as_text_key_label<class_InputEventKey_method_as_text_key_label>`\ (\ ) |const| |
|
|
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`String<class_String>` | :ref:`as_text_keycode<class_InputEventKey_method_as_text_keycode>`\ (\ ) |const| |
|
|
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`String<class_String>` | :ref:`as_text_location<class_InputEventKey_method_as_text_location>`\ (\ ) |const| |
|
|
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`String<class_String>` | :ref:`as_text_physical_keycode<class_InputEventKey_method_as_text_physical_keycode>`\ (\ ) |const| |
|
|
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Key<enum_@GlobalScope_Key>` | :ref:`get_key_label_with_modifiers<class_InputEventKey_method_get_key_label_with_modifiers>`\ (\ ) |const| |
|
|
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Key<enum_@GlobalScope_Key>` | :ref:`get_keycode_with_modifiers<class_InputEventKey_method_get_keycode_with_modifiers>`\ (\ ) |const| |
|
|
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Key<enum_@GlobalScope_Key>` | :ref:`get_physical_keycode_with_modifiers<class_InputEventKey_method_get_physical_keycode_with_modifiers>`\ (\ ) |const| |
|
|
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------+
|
|
|
|
.. rst-class:: classref-section-separator
|
|
|
|
----
|
|
|
|
.. rst-class:: classref-descriptions-group
|
|
|
|
屬性說明
|
|
--------
|
|
|
|
.. _class_InputEventKey_property_echo:
|
|
|
|
.. rst-class:: classref-property
|
|
|
|
:ref:`bool<class_bool>` **echo** = ``false`` :ref:`🔗<class_InputEventKey_property_echo>`
|
|
|
|
.. rst-class:: classref-property-setget
|
|
|
|
- |void| **set_echo**\ (\ value\: :ref:`bool<class_bool>`\ )
|
|
- :ref:`bool<class_bool>` **is_echo**\ (\ )
|
|
|
|
If ``true``, the key was already pressed before this event. An echo event is a repeated key event sent when the user is holding down the key.
|
|
|
|
\ **Note:** The rate at which echo events are sent is typically around 20 events per second (after holding down the key for roughly half a second). However, the key repeat delay/speed can be changed by the user or disabled entirely in the operating system settings. To ensure your project works correctly on all configurations, do not assume the user has a specific key repeat configuration in your project's behavior.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_InputEventKey_property_key_label:
|
|
|
|
.. rst-class:: classref-property
|
|
|
|
:ref:`Key<enum_@GlobalScope_Key>` **key_label** = ``0`` :ref:`🔗<class_InputEventKey_property_key_label>`
|
|
|
|
.. rst-class:: classref-property-setget
|
|
|
|
- |void| **set_key_label**\ (\ value\: :ref:`Key<enum_@GlobalScope_Key>`\ )
|
|
- :ref:`Key<enum_@GlobalScope_Key>` **get_key_label**\ (\ )
|
|
|
|
Represents the localized label printed on the key in the current keyboard layout, which corresponds to one of the :ref:`Key<enum_@GlobalScope_Key>` constants or any valid Unicode character. Key labels are meant for key prompts.
|
|
|
|
For keyboard layouts with a single label on the key, it is equivalent to :ref:`keycode<class_InputEventKey_property_keycode>`.
|
|
|
|
To get a human-readable representation of the **InputEventKey**, use ``OS.get_keycode_string(event.key_label)`` where ``event`` is the **InputEventKey**.
|
|
|
|
.. code:: text
|
|
|
|
+-----+ +-----+
|
|
| Q | | Q | - "Q" - keycode
|
|
| Й | | ض | - "Й" and "ض" - key_label
|
|
+-----+ +-----+
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_InputEventKey_property_keycode:
|
|
|
|
.. rst-class:: classref-property
|
|
|
|
:ref:`Key<enum_@GlobalScope_Key>` **keycode** = ``0`` :ref:`🔗<class_InputEventKey_property_keycode>`
|
|
|
|
.. rst-class:: classref-property-setget
|
|
|
|
- |void| **set_keycode**\ (\ value\: :ref:`Key<enum_@GlobalScope_Key>`\ )
|
|
- :ref:`Key<enum_@GlobalScope_Key>` **get_keycode**\ (\ )
|
|
|
|
Latin label printed on the key in the current keyboard layout, which corresponds to one of the :ref:`Key<enum_@GlobalScope_Key>` constants. Key codes are meant for shortcuts expressed with a standard Latin keyboard, such as :kbd:`Ctrl + S` for a "Save" shortcut.
|
|
|
|
To get a human-readable representation of the **InputEventKey**, use ``OS.get_keycode_string(event.keycode)`` where ``event`` is the **InputEventKey**.
|
|
|
|
.. code:: text
|
|
|
|
+-----+ +-----+
|
|
| Q | | Q | - "Q" - keycode
|
|
| Й | | ض | - "Й" and "ض" - key_label
|
|
+-----+ +-----+
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_InputEventKey_property_location:
|
|
|
|
.. rst-class:: classref-property
|
|
|
|
:ref:`KeyLocation<enum_@GlobalScope_KeyLocation>` **location** = ``0`` :ref:`🔗<class_InputEventKey_property_location>`
|
|
|
|
.. rst-class:: classref-property-setget
|
|
|
|
- |void| **set_location**\ (\ value\: :ref:`KeyLocation<enum_@GlobalScope_KeyLocation>`\ )
|
|
- :ref:`KeyLocation<enum_@GlobalScope_KeyLocation>` **get_location**\ (\ )
|
|
|
|
Represents the location of a key which has both left and right versions, such as :kbd:`Shift` or :kbd:`Alt`.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_InputEventKey_property_physical_keycode:
|
|
|
|
.. rst-class:: classref-property
|
|
|
|
:ref:`Key<enum_@GlobalScope_Key>` **physical_keycode** = ``0`` :ref:`🔗<class_InputEventKey_property_physical_keycode>`
|
|
|
|
.. rst-class:: classref-property-setget
|
|
|
|
- |void| **set_physical_keycode**\ (\ value\: :ref:`Key<enum_@GlobalScope_Key>`\ )
|
|
- :ref:`Key<enum_@GlobalScope_Key>` **get_physical_keycode**\ (\ )
|
|
|
|
Represents the physical location of a key on the 101/102-key US QWERTY keyboard, which corresponds to one of the :ref:`Key<enum_@GlobalScope_Key>` constants. Physical key codes meant for game input, such as WASD movement, where only the location of the keys is important.
|
|
|
|
To get a human-readable representation of the **InputEventKey**, use :ref:`OS.get_keycode_string()<class_OS_method_get_keycode_string>` in combination with :ref:`DisplayServer.keyboard_get_keycode_from_physical()<class_DisplayServer_method_keyboard_get_keycode_from_physical>` or :ref:`DisplayServer.keyboard_get_label_from_physical()<class_DisplayServer_method_keyboard_get_label_from_physical>`:
|
|
|
|
|
|
.. tabs::
|
|
|
|
.. code-tab:: gdscript
|
|
|
|
func _input(event):
|
|
if event is InputEventKey:
|
|
var keycode = DisplayServer.keyboard_get_keycode_from_physical(event.physical_keycode)
|
|
var label = DisplayServer.keyboard_get_label_from_physical(event.physical_keycode)
|
|
print(OS.get_keycode_string(keycode))
|
|
print(OS.get_keycode_string(label))
|
|
|
|
.. code-tab:: csharp
|
|
|
|
public override void _Input(InputEvent @event)
|
|
{
|
|
if (@event is InputEventKey inputEventKey)
|
|
{
|
|
var keycode = DisplayServer.KeyboardGetKeycodeFromPhysical(inputEventKey.PhysicalKeycode);
|
|
var label = DisplayServer.KeyboardGetLabelFromPhysical(inputEventKey.PhysicalKeycode);
|
|
GD.Print(OS.GetKeycodeString(keycode));
|
|
GD.Print(OS.GetKeycodeString(label));
|
|
}
|
|
}
|
|
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_InputEventKey_property_pressed:
|
|
|
|
.. rst-class:: classref-property
|
|
|
|
:ref:`bool<class_bool>` **pressed** = ``false`` :ref:`🔗<class_InputEventKey_property_pressed>`
|
|
|
|
.. rst-class:: classref-property-setget
|
|
|
|
- |void| **set_pressed**\ (\ value\: :ref:`bool<class_bool>`\ )
|
|
- :ref:`bool<class_bool>` **is_pressed**\ (\ )
|
|
|
|
如果為 ``true``\ ，按鍵的狀態是被按下。如果為 ``false``\ ，該鍵的狀態被釋放。
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_InputEventKey_property_unicode:
|
|
|
|
.. rst-class:: classref-property
|
|
|
|
:ref:`int<class_int>` **unicode** = ``0`` :ref:`🔗<class_InputEventKey_property_unicode>`
|
|
|
|
.. rst-class:: classref-property-setget
|
|
|
|
- |void| **set_unicode**\ (\ value\: :ref:`int<class_int>`\ )
|
|
- :ref:`int<class_int>` **get_unicode**\ (\ )
|
|
|
|
The key Unicode character code (when relevant), shifted by modifier keys. Unicode character codes for composite characters and complex scripts may not be available unless IME input mode is active. See :ref:`Window.set_ime_active()<class_Window_method_set_ime_active>` for more information. Unicode character codes are meant for text input.
|
|
|
|
\ **Note:** This property is set by the engine only for a pressed event. If the event is sent by an IME or a virtual keyboard, no corresponding key released event is sent.
|
|
|
|
.. rst-class:: classref-section-separator
|
|
|
|
----
|
|
|
|
.. rst-class:: classref-descriptions-group
|
|
|
|
方法說明
|
|
--------
|
|
|
|
.. _class_InputEventKey_method_as_text_key_label:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`String<class_String>` **as_text_key_label**\ (\ ) |const| :ref:`🔗<class_InputEventKey_method_as_text_key_label>`
|
|
|
|
返回該事件 :ref:`key_label<class_InputEventKey_property_key_label>` 及修飾鍵的 :ref:`String<class_String>` 字串表示。
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_InputEventKey_method_as_text_keycode:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`String<class_String>` **as_text_keycode**\ (\ ) |const| :ref:`🔗<class_InputEventKey_method_as_text_keycode>`
|
|
|
|
返回該事件 :ref:`keycode<class_InputEventKey_property_keycode>` 及修飾鍵的 :ref:`String<class_String>` 字串表示。
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_InputEventKey_method_as_text_location:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`String<class_String>` **as_text_location**\ (\ ) |const| :ref:`🔗<class_InputEventKey_method_as_text_location>`
|
|
|
|
Returns a :ref:`String<class_String>` representation of the event's :ref:`location<class_InputEventKey_property_location>`. This will be a blank string if the event is not specific to a location.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_InputEventKey_method_as_text_physical_keycode:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`String<class_String>` **as_text_physical_keycode**\ (\ ) |const| :ref:`🔗<class_InputEventKey_method_as_text_physical_keycode>`
|
|
|
|
返回該事件 :ref:`physical_keycode<class_InputEventKey_property_physical_keycode>` 及修飾鍵的 :ref:`String<class_String>` 字串表示。
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_InputEventKey_method_get_key_label_with_modifiers:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`Key<enum_@GlobalScope_Key>` **get_key_label_with_modifiers**\ (\ ) |const| :ref:`🔗<class_InputEventKey_method_get_key_label_with_modifiers>`
|
|
|
|
返回與修飾鍵，例如 :kbd:`Shift` 或 :kbd:`Alt` 組合的當地語系化鍵標籤。另見 :ref:`InputEventWithModifiers<class_InputEventWithModifiers>`\ 。
|
|
|
|
要獲得帶有修飾鍵的 **InputEventKey** 的人類可讀表示，請使用 ``OS.get_keycode_string(event.get_key_label_with_modifiers())``\ ，其中 ``event`` 是 **InputEventKey**\ 。
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_InputEventKey_method_get_keycode_with_modifiers:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`Key<enum_@GlobalScope_Key>` **get_keycode_with_modifiers**\ (\ ) |const| :ref:`🔗<class_InputEventKey_method_get_keycode_with_modifiers>`
|
|
|
|
返回與 :kbd:`Shift` 或 :kbd:`Alt` 等修飾鍵組合的拉丁鍵碼。另見 :ref:`InputEventWithModifiers<class_InputEventWithModifiers>`\ 。
|
|
|
|
要獲得帶有修飾鍵的 **InputEventKey** 的人類可讀表示，請使用 ``OS.get_keycode_string(event.get_keycode_with_modifiers())``\ ，其中 ``event`` 是 **InputEventKey**\ 。
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_InputEventKey_method_get_physical_keycode_with_modifiers:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`Key<enum_@GlobalScope_Key>` **get_physical_keycode_with_modifiers**\ (\ ) |const| :ref:`🔗<class_InputEventKey_method_get_physical_keycode_with_modifiers>`
|
|
|
|
返回與諸如 :kbd:`Shift` 或 :kbd:`Alt` 的修飾鍵組合的物理鍵碼。另請參閱 :ref:`InputEventWithModifiers<class_InputEventWithModifiers>`\ 。
|
|
|
|
要獲得帶有修飾符的 **InputEventKey** 的人類可讀表示，請使用 ``OS.get_keycode_string(event.get_physical_keycode_with_modifiers())``\ ，其中 ``event`` 是 **InputEventKey**\ 。
|
|
|
|
.. |virtual| replace:: :abbr:`virtual (本方法通常需要使用者覆寫才能生效。)`
|
|
.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)`
|
|
.. |const| replace:: :abbr:`const (本方法沒有副作用。不會修改該實例的任何成員變數。)`
|
|
.. |vararg| replace:: :abbr:`vararg (本方法除了這裡描述的參數外，還可以接受任意數量的參數。)`
|
|
.. |constructor| replace:: :abbr:`constructor (本方法用於建構一個型別。)`
|
|
.. |static| replace:: :abbr:`static (本方法無需實例即可呼叫，因此可以直接使用類別名稱呼叫。)`
|
|
.. |operator| replace:: :abbr:`operator (本方法描述將本型別作為左運算元時可用的有效運算子。)`
|
|
.. |bitfield| replace:: :abbr:`BitField (此值是由下列旗標組成的位元遮罩整數。)`
|
|
.. |void| replace:: :abbr:`void (無回傳值。)`
|