Processar ações do teclado
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Testar o Compose
O Jetpack Compose é o kit de ferramentas de interface recomendado para Android. Aprenda a processar ações de teclado no Compose.
Quando o usuário focaliza uma visualização de texto editável, como um
elemento
EditText
, e tem um teclado físico conectado, todas as
entradas são processadas pelo sistema. No entanto, se você quiser interceptar
ou processar diretamente a entrada do teclado, é preciso implementar métodos de callback
da interface KeyEvent.Callback
, como onKeyDown()
e onKeyMultiple()
.
As classes Activity
e View
implementam a
interface KeyEvent.Callback
. Portanto, geralmente é necessário
modificar os métodos de callback na extensão dessas classes, conforme
apropriado.
Observação:ao processar eventos de teclado com a
classe KeyEvent
e as APIs relacionadas,
espere que os eventos de teclado sejam provenientes apenas de um teclado físico. Nunca espere receber eventos de
nenhuma tecla em um método de entrada flexível (um teclado na tela).
Processar eventos de tecla única
Para processar o pressionamento de uma tecla individual, implemente
onKeyDown()
ou onKeyUp()
,
conforme apropriado. Normalmente, use
onKeyUp()
se você quiser garantir que receberá apenas um evento. Se o usuário tocar e manter uma tecla pressionada,
onKeyDown()
será chamado várias vezes.
Por exemplo, esta implementação responde a algumas teclas do teclado para controlar um jogo:
Kotlin
override fun onKeyUp(keyCode: Int, event: KeyEvent): Boolean {
return when (keyCode) {
KeyEvent.KEYCODE_D -> {
moveShip(MOVE_LEFT)
true
}
KeyEvent.KEYCODE_F -> {
moveShip(MOVE_RIGHT)
true
}
KeyEvent.KEYCODE_J -> {
fireMachineGun()
true
}
KeyEvent.KEYCODE_K -> {
fireMissile()
true
}
else -> super.onKeyUp(keyCode, event)
}
}
Java
@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
switch (keyCode) {
case KeyEvent.KEYCODE_D:
moveShip(MOVE_LEFT);
return true;
case KeyEvent.KEYCODE_F:
moveShip(MOVE_RIGHT);
return true;
case KeyEvent.KEYCODE_J:
fireMachineGun();
return true;
case KeyEvent.KEYCODE_K:
fireMissile();
return true;
default:
return super.onKeyUp(keyCode, event);
}
}
Processar teclas modificadoras
Para responder a eventos de tecla modificadora, como quando uma tecla é combinada com Shift
ou Control, você pode
consultar o KeyEvent
que é transmitido para o método de callback. Vários métodos
fornecem informações sobre teclas modificadoras, como
getModifiers()
e getMetaState()
.
No entanto, a solução mais simples é verificar se
a tecla modificadora exata está sendo pressionada com métodos como
isShiftPressed()
e isCtrlPressed()
.
Por exemplo, esta é a implementação de onKeyUp()
novamente, com um tratamento extra para quando a tecla Shift é mantida pressionada com uma das teclas:
Kotlin
override fun onKeyUp(keyCode: Int, event: KeyEvent): Boolean {
return when (keyCode) {
...
KeyEvent.KEYCODE_J -> {
if (event.isShiftPressed) {
fireLaser()
} else {
fireMachineGun()
}
true
}
KeyEvent.KEYCODE_K -> {
if (event.isShiftPressed) {
fireSeekingMissle()
} else {
fireMissile()
}
true
}
else -> super.onKeyUp(keyCode, event)
}
}
Java
@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
switch (keyCode) {
...
case KeyEvent.KEYCODE_J:
if (event.isShiftPressed()) {
fireLaser();
} else {
fireMachineGun();
}
return true;
case KeyEvent.KEYCODE_K:
if (event.isShiftPressed()) {
fireSeekingMissle();
} else {
fireMissile();
}
return true;
default:
return super.onKeyUp(keyCode, event);
}
}
Outros recursos
O conteúdo e os exemplos de código nesta página estão sujeitos às licenças descritas na Licença de conteúdo. Java e OpenJDK são marcas registradas da Oracle e/ou suas afiliadas.
Última atualização 2025-07-26 UTC.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-07-26 UTC."],[],[],null,["# Handle keyboard actions\n\nTry the Compose way \nJetpack Compose is the recommended UI toolkit for Android. Learn how to handle keyboard actions in Compose. \n[Handle keyboard actions in Compose →](/develop/ui/compose/touch-input/keyboard-input/commands#key_events) \n\nWhen the user gives focus to an editable text view, such as an\n[EditText](/reference/android/widget/EditText)\nelement, and the user has a hardware keyboard attached, all\ninput is handled by the system. However, if you want to intercept\nor directly handle the keyboard input yourself, you can do so by implementing callback methods\nfrom the [KeyEvent.Callback](/reference/android/view/KeyEvent.Callback)\ninterface, such as [onKeyDown()](/reference/android/view/KeyEvent.Callback#onKeyDown(int, android.view.KeyEvent))\nand [onKeyMultiple()](/reference/android/view/KeyEvent.Callback#onKeyMultiple(int, int, android.view.KeyEvent)).\n\nBoth the [Activity](/reference/android/app/Activity)\nand [View](/reference/android/view/View) classes implement the\n`KeyEvent.Callback` interface, so you\ngenerally override the callback methods in your extension of these classes, as\nappropriate.\n\n**Note:** When handling keyboard events with the\n[KeyEvent](/reference/android/view/KeyEvent) class and related APIs,\nexpect that the keyboard events are coming only from a hardware keyboard. Never rely on receiving key\nevents for any key on a soft input method (an on-screen keyboard).\n\nHandle single key events\n------------------------\n\nTo handle an individual key press, implement\n[onKeyDown()](/reference/android/app/Activity#onKeyDown(int, android.view.KeyEvent))\nor [onKeyUp()](/reference/android/app/Activity#onKeyUp(int, android.view.KeyEvent)),\nas appropriate. Usually, you use\n`onKeyUp()`\nif you want to ensure that you receive only one event. If the user presses and holds a key,\nthen `onKeyDown()` is called multiple times.\n\nFor example, this implementation responds to some keyboard keys to control a game: \n\n### Kotlin\n\n```kotlin\noverride fun onKeyUp(keyCode: Int, event: KeyEvent): Boolean {\n return when (keyCode) {\n KeyEvent.KEYCODE_D -\u003e {\n moveShip(MOVE_LEFT)\n true\n }\n KeyEvent.KEYCODE_F -\u003e {\n moveShip(MOVE_RIGHT)\n true\n }\n KeyEvent.KEYCODE_J -\u003e {\n fireMachineGun()\n true\n }\n KeyEvent.KEYCODE_K -\u003e {\n fireMissile()\n true\n }\n else -\u003e super.onKeyUp(keyCode, event)\n }\n}\n```\n\n### Java\n\n```java\n@Override\npublic boolean onKeyUp(int keyCode, KeyEvent event) {\n switch (keyCode) {\n case KeyEvent.KEYCODE_D:\n moveShip(MOVE_LEFT);\n return true;\n case KeyEvent.KEYCODE_F:\n moveShip(MOVE_RIGHT);\n return true;\n case KeyEvent.KEYCODE_J:\n fireMachineGun();\n return true;\n case KeyEvent.KEYCODE_K:\n fireMissile();\n return true;\n default:\n return super.onKeyUp(keyCode, event);\n }\n}\n```\n\nHandle modifier keys\n--------------------\n\nTo respond to modifier key events, such as when a key is combined with \u003ckbd\u003eShift\u003c/kbd\u003e\nor \u003ckbd\u003eControl\u003c/kbd\u003e, you can\nquery the `KeyEvent`\nthat is passed to the callback method. Several methods\nprovide information about modifier keys, such as\n[getModifiers()](/reference/android/view/KeyEvent#getModifiers())\nand [getMetaState()](/reference/android/view/KeyEvent#getMetaState()).\nHowever, the simplest solution is to check whether\nthe exact modifier key you care about is being pressed with methods such as\n[isShiftPressed()](/reference/android/view/KeyEvent#isShiftPressed())\nand [isCtrlPressed()](/reference/android/view/KeyEvent#isCtrlPressed()).\n\nFor example, here's the `onKeyUp()` implementation\nagain, with extra handling for when the \u003ckbd\u003eShift\u003c/kbd\u003e key is held down with one of the keys: \n\n### Kotlin\n\n```kotlin\noverride fun onKeyUp(keyCode: Int, event: KeyEvent): Boolean {\n return when (keyCode) {\n ...\n KeyEvent.KEYCODE_J -\u003e {\n if (event.isShiftPressed) {\n fireLaser()\n } else {\n fireMachineGun()\n }\n true\n }\n KeyEvent.KEYCODE_K -\u003e {\n if (event.isShiftPressed) {\n fireSeekingMissle()\n } else {\n fireMissile()\n }\n true\n }\n else -\u003e super.onKeyUp(keyCode, event)\n }\n}\n```\n\n### Java\n\n```java\n@Override\npublic boolean onKeyUp(int keyCode, KeyEvent event) {\n switch (keyCode) {\n ...\n case KeyEvent.KEYCODE_J:\n if (event.isShiftPressed()) {\n fireLaser();\n } else {\n fireMachineGun();\n }\n return true;\n case KeyEvent.KEYCODE_K:\n if (event.isShiftPressed()) {\n fireSeekingMissle();\n } else {\n fireMissile();\n }\n return true;\n default:\n return super.onKeyUp(keyCode, event);\n }\n}\n```\n\nAdditional resources\n--------------------\n\n- [Keyboard Shortcuts Helper](/develop/ui/compose/touch-input/keyboard-input/keyboard-shortcuts-helper): System screen that enables users to search the keyboard shortcuts your app offers."]]