chore: Converted pt-BR/docs/web/api/keyboardevent to MD

[nathipg]

No description provided.

[github-actions]

Preview URLs

• https://pr7253.content.dev.mdn.mozit.cloud/pt-BR/docs/Web/API/KeyboardEvent

Flaws

URL: /pt-BR/docs/Web/API/KeyboardEvent
Title: KeyboardEvent
on GitHub
Flaw count: 32

• macros:
  • /pt-BR/docs/Web/API/KeyboardEvent/KeyboardEvent does not exist but fell back to /en-US/docs/Web/API/KeyboardEvent/KeyboardEvent
  • /pt-BR/docs/Web/API/UIEvent does not exist but fell back to /en-US/docs/Web/API/UIEvent
  • /pt-BR/docs/Web/API/KeyboardEvent/getModifierState does not exist but fell back to /en-US/docs/Web/API/KeyboardEvent/getModifierState
  • /pt-BR/docs/Web/API/KeyboardEvent/initKeyEvent does not exist but fell back to /en-US/docs/Web/API/KeyboardEvent/initKeyEvent
  • /pt-BR/docs/Web/API/KeyboardEvent/initKeyboardEvent does not exist but fell back to /en-US/docs/Web/API/KeyboardEvent/initKeyboardEvent
  • and 26 more flaws omitted
• translation_differences:
  • Differences in the important macros (2 in common of 4 possible)

External URLs

URL: /pt-BR/docs/Web/API/KeyboardEvent
Title: KeyboardEvent
on GitHub

No new external URLs

(this comment was updated 2022-08-04 01:09:33.425906)

[josielrocha]

Esse arquivo já está um pouco desatualizado e, além disso, tem algumas partes que ainda carecem de tradução.

Tomei a liberdade de fazer a tradução, mas não posso adicionar como sugestão usando a opção do GitHub porque há agum conflito que quebra o código.

Segue:

---
title: KeyboardEvent
slug: Web/API/KeyboardEvent
page-type: web-api-interface
tags:
  - API
  - DOM
  - Event
  - Input
  - Interface
  - Key Events
  - Keyboard Events
  - KeyboardEvent
  - MakeBrowserAgnostic
  - Reference
  - UI Events
  - keyboard
  - user input
browser-compat: api.KeyboardEvent
translation_of: Web/API/KeyboardEvent
---
{{APIRef("Eventos de IU")}}

Objetos **`KeyboardEvent`** descrevem uma interação do usuário com o teclado; cada evento descreve uma única interação entre o usuário e uma tecla (ou combinação de uma tecla com teclas modificadoras) no teclado. O tipo de evento ({{domxref("Element/keydown_event", "keydown")}}, {{domxref("Element/keypress_event", "keypress")}} ou {{domxref("Element/keyup_event", " keyup")}}) identifica que tipo de atividade do teclado ocorreu.

> **Observação:** eventos `KeyboardEvent` apenas indicam qual interação o usuário teve com uma tecla do teclado em um nível baixo, não fornecendo nenhum significado contextual para essa interação. Quando você precisar manipular a entrada de texto, use o evento {{domxref("HTMLElement/input_event", "input")}}. Os eventos de teclado não podem ser acionados se o usuário estiver usando um meio alternativo de inserir texto, como um sistema de escrita manual em um tablet ou mesa digitalizadora.

{{InheritanceDiagram}}

## Construtor

- {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}
  - : Cria um novo objeto `KeyboardEvent`.

## Constantes

A interface `KeyboardEvent` define as seguintes constantes.

### Localizações do teclado

As constantes a seguir identificam de qual parte do teclado o evento de tecla se origina. Eles são acessados ​​como `KeyboardEvent.DOM_KEY_LOCATION_STANDARD` e assim por diante.


  
    Keyboard location identifiers
  
  

    

      
Constante
      
Valor
      
Descrição
    
  
  

    

      
DOM_KEY_LOCATION_STANDARD
      
0x00
      

        

          A chave descrita pelo evento não é identificada como estando localizada em uma
          área específica do teclado; não está localizado no teclado
          numérico (a menos que seja a tecla NumLock) e para teclas duplicadas
          nos lados esquerdo e direito do teclado, a tecla é, seja qual for
          motivo, não estar associado a esse local.
        
        

          Exemplos incluem teclas alfanuméricas no teclado padrão PC 101 US,
          a tecla NumLock e a barra de espaço.
        
      
    
    

      
DOM_KEY_LOCATION_LEFT
      
0x01
      

        

          A tecla é aquela que pode existir em vários locais no teclado
          e, neste caso, está no lado esquerdo do teclado.
        
        

          Os exemplos incluem a tecla Control esquerda, a tecla Command esquerda em um
          teclado Macintosh ou a tecla Shift esquerda.
        
      
    
    

      
DOM_KEY_LOCATION_RIGHT
      
0x02
      

        

          A tecla é aquela que pode existir em várias posições no teclado
          e, neste caso, está localizado no lado direito do teclado.
        
        

          Os exemplos incluem a tecla Shift direita e a tecla Alt direita (Opção no
          um teclado Mac).
        
      
    
    

      
DOM_KEY_LOCATION_NUMPAD
      
0x03
      

        

          A tecla está localizada no teclado numérico ou é uma tecla virtual
          associado ao teclado numérico se houver mais de um lugar
          chave poderia se originar. A tecla NumLock não se enquadra nisso
          grupo e é sempre codificado com a localização
          DOM_KEY_LOCATION_STANDARD.
        
        

          Os exemplos incluem os dígitos no teclado numérico, a tecla Enter do teclado
          tecla e o ponto decimal no teclado.
        
      
    
  


## Propriedades

_Esta interface também herda as propriedades de seus pais, {{domxref("UIEvent")}} e {{domxref("Event")}}._

- {{domxref("KeyboardEvent.altKey")}} {{Readonlyinline}}

  - : Retorna um valor booleano que é `true` se a chave Alt (Option ou ⌥ no macOS) estava ativa quando o evento de chave foi gerado.

- {{domxref("KeyboardEvent.code")}} {{Readonlyinline}}

  - : Retorna uma string com o valor do código da chave física representada pelo evento.

    > **Aviso:** isso ignora o layout de teclado do usuário, de modo que, se o usuário pressionar a tecla na posição "Y" em um layout de teclado QWERTY (perto do meio da linha acima da linha inicial), isso sempre retornará "KeyY", mesmo que o usuário tenha um teclado QWERTZ (o que significa que o usuário espera um "Z" e todas as outras propriedades indicariam um "Z") ou um layout de teclado Dvorak (onde o usuário espera um "F" ). Se você deseja exibir o pressionamento de tecla corretos para o usuário, você pode usar {{domxref("Keyboard.getLayoutMap()")}}.

- {{domxref("KeyboardEvent.ctrlKey")}} {{Readonlyinline}}

  - : Retorna um valor booleano que é `true` se a tecla Ctrl estava ativa quando o evento de chave foi gerado.

- {{domxref("KeyboardEvent.isComposing")}} {{Readonlyinline}}
  - : Retorna um valor booleano que é `true` se o evento for disparado entre depois de `compositionstart` e antes de `compositionend`.
- {{domxref("KeyboardEvent.key")}} {{Readonlyinline}}
  - : Retorna uma string representando o valor da chave representada pelo evento.
- {{domxref("KeyboardEvent.locale")}} {{Readonlyinline}}

  - : Retorna uma string representando uma string de localidade indicando a localidade para a qual o teclado está configurado. Esta pode ser a string vazia se o navegador ou dispositivo não souber a localidade do teclado.

    > **Observação:** isso não descreve a localidade dos dados que estão sendo inseridos. Um usuário pode estar usando um layout de teclado ao digitar texto em um idioma diferente.

- {{domxref("KeyboardEvent.location")}} {{Readonlyinline}}
  - : Retorna um número que representa a localização da tecla no teclado ou outro dispositivo de entrada. Uma lista das constantes que identificam os locais é mostrada acima em [Locais do teclado](#keyboard_locations).
- {{domxref("KeyboardEvent.metaKey")}} {{Readonlyinline}}

  - : Retorna um valor booleano que é `true` se a tecla Meta (nos teclados Mac, a tecla ⌘ Command; nos teclados Windows, a tecla Windows ( ⊞)) estava ativo quando o evento de chave foi gerado.

- {{domxref("KeyboardEvent.repeat")}} {{Readonlyinline}}
  - : Retorna um valor booleano que é `true` se a tecla estiver sendo mantida pressionada de forma que se repita automaticamente.
- {{domxref("KeyboardEvent.shiftKey")}} {{Readonlyinline}}

  - : Retorna um valor booleano que é `true` se a tecla Shift estava ativa quando o evento de chave foi gerado.

## Métodos

_Esta interface também herda métodos de seus pais, {{domxref("UIEvent")}} e {{domxref("Event")}}._

- {{domxref("KeyboardEvent.getModifierState()")}}

  - : Retorna um valor booleano indicando se uma tecla modificadora como Alt, Shift, Ctrl ou Meta, foi pressionado quando o evento foi criado.

## Métodos obsoletos

- {{domxref("KeyboardEvent.initKeyEvent()")}} {{deprecated_inline}}
  - : Inicializa um objeto `KeyboardEvent`. Isso foi implementado apenas pelo Firefox e não é mais suportado lá; em vez disso, você deve usar o construtor {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}.
- {{domxref("KeyboardEvent.initKeyboardEvent()")}} {{deprecated_inline}}
  - : Inicializa um objeto `KeyboardEvent`. Isso agora está obsoleto. Em vez disso, você deve usar o construtor {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}.

## Propriedades obsoletas

- {{domxref("KeyboardEvent.char")}} {{Non-standard_inline}} {{Deprecated_inline}} {{Readonlyinline}}

  - : Retorna uma string representando o valor do caractere da chave. Se a chave corresponder a um caractere imprimível, esse valor será uma string Unicode não vazia contendo esse caractere. Se a chave não tiver uma representação imprimível, esta é uma string vazia.

    > **Observação:** se a chave for usada como uma macro que insere vários caracteres, o valor dessa propriedade será a string inteira, não apenas o primeiro caractere.

- {{domxref("KeyboardEvent.charCode")}} {{Deprecated_inline}} {{Readonlyinline}}

  - : Retorna um número que representa o número de referência Unicode da chave; esta propriedade é usada apenas pelo evento `keypress`. Para chaves cuja propriedade `char` contém vários caracteres, este é o valor Unicode do primeiro caractere dessa propriedade. No Firefox 26, isso retorna códigos para caracteres imprimíveis.

    > **Aviso:** esta propriedade está obsoleta; você deve usar {{domxref("KeyboardEvent.key")}} em vez disso, se disponível.

- {{domxref("KeyboardEvent.keyCode")}} {{deprecated_inline}} {{Readonlyinline}}

  - : Retorna um número que representa um código numérico dependente do sistema e da implementação que identifica o valor não modificado da tecla pressionada.

    > **Aviso:** esta propriedade está obsoleta; você deve usar {{domxref("KeyboardEvent.key")}} em vez disso, se disponível.

- {{domxref("KeyboardEvent.keyIdentifier")}} {{Non-standard_inline}} {{deprecated_inline}} {{Readonlyinline}}
  - : Esta propriedade não é padrão e foi preterida em favor de {{domxref("KeyboardEvent.key")}}. Fazia parte de uma versão antiga do DOM Level 3 Events.
- {{domxref("KeyboardEvent.keyLocation")}} {{Non-standard_inline}} {{deprecated_inline}} {{Readonlyinline}}
  - : este é um alias obsoleto não padrão para {{domxref("KeyboardEvent.location")}}. Fazia parte de uma versão antiga do DOM Level 3 Events.
- {{domxref("KeyboardEvent.which")}} {{deprecated_inline}} {{Readonlyinline}}

  - : Retorna um número que representa um código numérico dependente do sistema e da implementação que identifica o valor não modificado da tecla pressionada; isso geralmente é o mesmo que `keyCode`.

    > **Aviso:** Esta propriedade está obsoleta; você deve usar {{domxref("KeyboardEvent.key")}} em vez disso, se disponível.

## Eventos

Os eventos a seguir são baseados no tipo `KeyboardEvent`. Eles podem ser entregues a qualquer objeto que implemente {{domxref("GlobalEventHandlers")}}, incluindo {{domxref("Element")}}, {{domxref("Document")}} e {{domxref("Window ")}}. Na lista abaixo, cada evento tem um link para a documentação do manipulador `Element` do evento, que se aplica geralmente a todos os destinatários.

- {{domxref("Element.keydown_event", "keydown")}}
  - : Uma tecla foi pressionada.
- {{domxref("Element.keyup_event", "keyup")}}
  - : Uma tecla foi liberada.

### Eventos obsoletos

- {{domxref("Element.keypress_event", "keypress")}} {{deprecated_inline}}
  - : Uma tecla que normalmente produz um valor de caractere foi pressionada. Este evento era altamente dependente do dispositivo e é obsoleto. Você não deve usá-lo.

## Notas de uso

Existem três tipos de eventos de teclado: {{domxref("Element/keydown_event", "keydown")}}, {{domxref("Element/keypress_event", "keypress")}} e {{domxref("Element/ keyup_event", "keyup")}}. Para a maioria das chaves, o Gecko despacha uma sequência de eventos de chave como esta:

1. Quando a tecla é pressionada pela primeira vez, o evento `keydown` é enviado.
2. Se a tecla não for uma tecla modificadora, o evento `keypress` será enviado.
3. Quando o usuário libera a chave, o evento `keyup` é enviado.

### Casos especiais

Algumas teclas alternam o estado de uma luz indicadora; isso inclui teclas como Caps Lock, Num Lock e Scroll Lock. No Windows e no Linux, essas chaves despacham apenas os eventos `keydown` e `keyup`.

> **Observação:** No Linux, o Firefox 12 e versões anteriores também despacharam o evento `keypress` para essas teclas.

No entanto, uma limitação do modelo de evento do macOS faz com que o Caps Lock despache apenas o evento `keydown`. O Num Lock era suportado em alguns modelos de laptop mais antigos (modelos de 2007 e anteriores), mas desde então, o macOS não suporta o Num Lock, mesmo em teclados externos. Em MacBooks mais antigos com uma tecla Num Lock, essa tecla não gera nenhum evento de tecla. Gecko suporta a tecla Scroll Lock se um teclado externo que possui uma tecla F14 estiver conectado. Em certas versões mais antigas do Firefox, essa chave gerava um evento `keypress`; este comportamento inconsistente foi {{bug(602812)}}.

### Manipulação de repetição automática

Quando uma tecla é pressionada e mantida pressionada, ela começa a se repetir automaticamente. Isso resulta em uma sequência de eventos semelhante à seguinte sendo despachada:

1. `keydown`
2. `keypress`
3. `keydown`
4. `keypress`
5. <\>
6. `keyup`

Isso é o que a especificação do DOM Nível 3 diz que deve acontecer. Há algumas ressalvas, no entanto, conforme descrito abaixo.

#### Repetição automática em alguns ambientes GTK, como o Ubuntu 9.4

Em alguns ambientes baseados em GTK, a repetição automática despacha um evento de ativação de tecla nativo automaticamente durante a repetição automática, e não há como o Gecko saber a diferença entre uma série repetida de pressionamentos de tecla e uma repetição automática. Nessas plataformas, então, uma chave de repetição automática gerará a seguinte sequência de eventos:

1. `keydown`
2. `keypress`
3. `keyup`
4. `keydown`
5. `keypress`
6. `keyup`
7. <\>
8. `keyup`

Nesses ambientes, infelizmente, não há como o conteúdo da Web dizer a diferença entre teclas de repetição automática e teclas que estão sendo pressionadas repetidamente.

#### Manipulação de repetição automática antes do Gecko 5.0

Antes do Gecko 5.0 {{geckoRelease('5.0')}}, o manuseio do teclado era menos consistente entre as plataformas.

- Windows
  - : O comportamento de repetição automática é o mesmo do Gecko 4.0 e posterior.
- Mac
  - : Após o evento keydown inicial, somente os eventos keypress são enviados até que o evento keyup ocorra; os eventos de keydown entre espaços não são enviados.
- Linux
  - : O comportamento do evento depende da plataforma específica. Ele se comportará como Windows ou Mac, dependendo do que o modelo de evento nativo faz.

> **Observação:** o disparo manual de um evento _não_ gera a ação padrão associada a esse evento.
> Por exemplo, disparar manualmente um evento de tecla não faz com que essa letra apareça em uma entrada de texto focada.
> No caso de eventos de UI, isso é importante por questões de segurança, pois evita que scripts simulem ações do usuário que interagem com o próprio navegador.

## Exemplo

``` js
document.addEventListener('keydown', (evento) => {
  const keyName = event.key;

  if (keyName === 'Control') {
    // não alerta quando apenas a tecla Control é pressionada.
    return;
  }

  if (evento.ctrlKey) {
    // Mesmo que event.key não seja 'Control' (por exemplo, 'a' é pressionado),
    // event.ctrlKey pode ser true se a tecla Ctrl for pressionada ao mesmo tempo.
    alert(`Combinação de ctrlKey + ${keyName}`);
  } senão {
    alert(`Tecla pressionada ${keyName}`);
  }
}, false);

document.addEventListener('keyup', (evento) => {
  const keyName = event.key;

  // Conforme o usuário libera a tecla Ctrl, a tecla não está mais ativa,
  // então event.ctrlKey é false.
  if (keyName === 'Controle') {
    alert('A chave de controle foi liberada');
  }
}, false);
```

## Especificações

{{Especificações}}

A especificação da interface `KeyboardEvent` passou por várias versões de rascunho, primeiro em DOM Events Level 2, onde foi descartada porque não havia consenso, depois em DOM Events Level 3. Isso levou à implementação de métodos de inicialização não padrão, os primeiros DOM Events Versão de nível 2, {{domxref("KeyboardEvent.initKeyEvent()")}} pelos navegadores Gecko e a versão inicial do DOM Events Nível 3, {{domxref("KeyboardEvent.initKeyboardEvent()")}} por outros. Ambos foram substituídos pelo uso moderno de um construtor: {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}.

## Compatibilidade do navegador

{{Compat}}

### Notas de compatibilidade

- A partir do Firefox 65, o evento `keypress` não é mais acionado para [teclas não imprimíveis]() ({{bug(968056)}}), exceto para a tecla

  Enter

  , e o

  Shift

  \+

  Enter

  e

  Ctrl

  \+

  Enter

  combinações de teclas (estas foram mantidas para fins de compatibilidade entre navegadores).

## Veja também

- {{domxref("KeyboardEvent.code")}}.
- {{domxref("KeyboardEvent.key")}}.
- {{domxref("KeyboardEvent.getModifierState()")}}

[SphinxKnight]

subsumed by work on #7950