diff options
Diffstat (limited to 'files/pt-br/web/api/keyboardevent/index.html')
| -rw-r--r-- | files/pt-br/web/api/keyboardevent/index.html | 439 |
1 files changed, 439 insertions, 0 deletions
diff --git a/files/pt-br/web/api/keyboardevent/index.html b/files/pt-br/web/api/keyboardevent/index.html new file mode 100644 index 0000000000..d552857d3f --- /dev/null +++ b/files/pt-br/web/api/keyboardevent/index.html @@ -0,0 +1,439 @@ +--- +title: KeyboardEvent +slug: Web/API/KeyboardEvent +tags: + - API + - DOM + - Evento + - Inteface + - Referencia +translation_of: Web/API/KeyboardEvent +--- +<p>{{APIRef("DOM Events")}}</p> + +<p><code>Objetos do tipo <strong>KeyboardEvent</strong></code> descrevem a interação do usuário com o teclado. Cada evento descreve uma tecla; o tipo de evento (<code>keydown</code>, <code>keypress</code>, ou <code>keyup</code>) identifica qual tipo de ação foi executada.</p> + +<div class="note"><strong>Note:</strong> O <code>KeyboardEvent</code> indica o que está havendo com a tecla. Quando você precisar lidar com entrada de texto, use o evento <code><a href="/en-US/docs/DOM/DOM_event_reference/input" rel="custom">input</a> do </code>HTML5 . Por exemplo, se o usuário envia texto por meio de um sistema manuscrito como um tablet PC, eventos das teclas podem não ser disparados.</div> + +<h2 id="Construtor">Construtor</h2> + +<dl> + <dt>{{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}</dt> + <dd>Cria um objeto do tipo <code>KeyboardEvent</code>.</dd> +</dl> + +<h2 id="Métodos">Métodos</h2> + +<p><em>Essa interface também herda métodos dos seus pais, {{domxref("UIEvent")}} e {{domxref("Event")}}.</em></p> + +<dl> + <dt>{{domxref("KeyboardEvent.getModifierState()")}}</dt> + <dd>Retorna um {{jsxref("Boolean")}} indicando se uma tecla, como <kbd>Alt</kbd>, <kbd>Shift</kbd>, <kbd>Ctrl</kbd>, ou <kbd>Meta</kbd>, foi pressionada quando o evento foi criado.</dd> + <dt>{{domxref("KeyboardEvent.initKeyEvent()")}}{{deprecated_inline}}</dt> + <dd>Inicializa um objeto do tipo <code>KeyboardEvent</code> . isso foi apenas implementado por Gecko (outros usaram {{domxref("KeyboardEvent.initKeyboardEvent()")}}) e não deve mais ser usado. A forma moderna padrão é usar o construtor {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}.</dd> + <dt>{{domxref("KeyboardEvent.initKeyboardEvent()")}}{{deprecated_inline}}</dt> + <dd>Inicializa um objeto do tipo <code>KeyboardEvent</code> . Isso nunca foi implementado por Gecko (que usou {{domxref("KeyboardEvent.initKeyEvent()")}}) e não deve mais ser usado. A forma moderna padrão é usar o construtor {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}.</dd> +</dl> + +<h2 id="Propriedades">Propriedades</h2> + +<p><em>Essa interface também herda métodos dos seus pais, {{domxref("UIEvent")}} e {{domxref("Event")}}.</em></p> + +<dl> + <dt>{{domxref("KeyboardEvent.altKey")}} {{Readonlyinline}}</dt> + <dd>Retorna um {{jsxref("Boolean")}} que é <code>true</code> se a tecla <kbd>Alt</kbd> ( <kbd>Option</kbd> ou <kbd>⌥</kbd> no OS X) estava ativa quando o evento foi acionado.</dd> + <dt>{{domxref("KeyboardEvent.char")}} {{Non-standard_inline}}{{Deprecated_inline}}{{Readonlyinline}}</dt> + <dd>Retorna um {{domxref("DOMString")}} representando o valor da tecla em caractere. Se a tecla corresponde a um caractere exibível, esse valor é uma string Unicode não-vazia contendo aquele caractere. Se a tecla não possui uma representação exibível, ela é uma string vazia. + <div class="note"><strong>Nota:</strong> Se a tecla é usada como um macro que insere caracteres múltiplos, o valor desse atributo é a string inteira, não apenas o primeiro caractere.</div> + + <div class="warning"><strong>Aviso:</strong> Isso foi removido dos Eventos DOM de nível 3. Isso é apenas suportado no IE.</div> + </dd> + <dt>{{domxref("KeyboardEvent.charCode")}} {{Deprecated_inline}}{{Readonlyinline}}</dt> + <dd>Returns a {{jsxref("Number")}} representing the Unicode reference number of the key; this attribute is used only by the <code>keypress</code> event. For keys whose <code>char</code> attribute contains multiple characters, this is the Unicode value of the first character in that attribute. In Firefox 26 this returns codes for printable characters. + <div class="warning"><strong>Aviso:</strong> Este atributo esta depreciado; você deve usar <code>key</code> no lugar, se disponivel.</div> + </dd> + <dt>{{domxref("KeyboardEvent.code")}} {{Readonlyinline}}</dt> + <dd>Returns a {{domxref("DOMString")}} with the code value of the key represented by the event.</dd> + <dt>{{domxref("KeyboardEvent.ctrlKey")}} {{Readonlyinline}}</dt> + <dd>Returns a {{jsxref("Boolean")}} that is <code>true</code> if the <kbd>Ctrl</kbd> key was active when the key event was generated.</dd> + <dt>{{domxref("KeyboardEvent.isComposing")}} {{Readonlyinline}}</dt> + <dd>Returns a {{jsxref("Boolean")}} that is <code>true</code> if the event is fired between after <code>compositionstart</code> and before <code>compositionend</code>.</dd> + <dt>{{domxref("KeyboardEvent.key")}} {{Readonlyinline}}</dt> + <dd>Returns a {{domxref("DOMString")}} representing the key value of the key represented by the event.</dd> + <dt>{{domxref("KeyboardEvent.keyCode")}} {{deprecated_inline}}{{Readonlyinline}}</dt> + <dd>Returns a {{jsxref("Number")}} representing a system and implementation dependent numerical code identifying the unmodified value of the pressed key. + <div class="warning"><strong>Aviso:</strong> Este atributo esta depreciado; você deve usar <code>key</code> no lugar, se disponivel.</div> + </dd> + <dt>{{domxref("KeyboardEvent.locale")}} {{Readonlyinline}}</dt> + <dd>Returns a {{domxref("DOMString")}} representing a locale string indicating the locale the keyboard is configured for. This may be the empty string if the browser or device doesn't know the keyboard's locale. + <div class="note"><strong>Note:</strong> This does not describe the locale of the data being entered. A user may be using one keyboard layout while typing text in a different language.</div> + </dd> + <dt>{{domxref("KeyboardEvent.location")}}<a> {{Readonlyinline}}</a></dt> + <dd>Returns a {{jsxref("Number")}} representing the location of the key on the keyboard or other input device.</dd> + <dt>{{domxref("KeyboardEvent.metaKey")}} {{Readonlyinline}}</dt> + <dd>Returns a {{jsxref("Boolean")}} that is <code>true</code> if the <kbd>Meta</kbd> (or <kbd>Command</kbd> on OS X) key was active when the key event was generated.</dd> + <dt>{{domxref("KeyboardEvent.repeat")}} {{Readonlyinline}}</dt> + <dd>Returns a {{jsxref("Boolean")}} that is <code>true</code> if the key is being held down such that it is automatically repeating.</dd> + <dt>{{domxref("KeyboardEvent.shiftKey")}} {{Readonlyinline}}</dt> + <dd>Returns a {{jsxref("Boolean")}} that is <code>true</code> if the <kbd>Shift</kbd> key was active when the key event was generated.</dd> + <dt>{{domxref("KeyboardEvent.which")}} {{deprecated_inline}}{{Readonlyinline}}</dt> + <dd>Returns a {{jsxref("Number")}} representing a system and implementation dependent numeric code identifying the unmodified value of the pressed key; this is usually the same as <code>keyCode</code>. + <div class="warning"><strong>Aviso:</strong> Este atributo esta depreciado; você deve usar <code>key</code> no lugar, se disponivel.</div> + </dd> +</dl> + +<h2 id="Notes">Notes</h2> + +<p>There are <code>keydown</code>, <code>keypress</code>, and <code>keyup</code> events. For most keys, Gecko dispatches a sequence of key events like this:</p> + +<ol> + <li>When the key is first depressed, the <code>keydown</code> event is sent.</li> + <li>If the key is not a modifier key, the <code>keypress</code> event is sent.</li> + <li>When the user releases the key, the <code>keyup</code> event is sent.</li> +</ol> + +<h3 id="Special_cases">Special cases</h3> + +<p>Certain keys toggle the state of an LED indicator, such as Caps Lock, Num Lock, and Scroll Lock. On Windows and Linux, these keys dispatch only the <code>keydown</code> and <code>keyup</code> events. Note that on Linux, Firefox 12 and earlier also dispatched the <code>keypress</code> event for these keys.</p> + +<p>On Mac, however, Caps Lock dispatches only the <code>keydown</code> event due to a platform event model limitation. Num Lock had been supported on old MacBook (2007 model and older) but Mac hasn't supported Num Lock feature even on external keyboards in these days. On the old MacBook which has Num Lock key, Num Lock doesn't cause any key events. And Gecko supports Scroll Lock key if an external keyboard which has F14 is connected. However, it generates <code>keypress</code> event. This inconsistent behavior is a bug; see {{bug(602812)}}.</p> + +<h3 id="Auto-repeat_handling">Auto-repeat handling</h3> + +<p>When a key is pressed and held down, it begins to auto-repeat. This results in a sequence of events similar to the following being dispatched:</p> + +<ol> + <li><code>keydown</code></li> + <li><code>keypress</code></li> + <li><<repeating until the user releases the key>></li> + <li><code>keyup</code></li> +</ol> + +<p>This is what the DOM Level 3 specification says should happen. There are some caveats, however, as described below.</p> + +<h4 id="Auto-repeat_on_some_GTK_environments_such_as_Ubuntu_9.4">Auto-repeat on some GTK environments such as Ubuntu 9.4</h4> + +<p>In some GTK-based environments, auto-repeat dispatches a native key-up event automatically during auto-repeat, and there's no way for Gecko to know the difference between a repeated series of keypresses and an auto-repeat. On those platforms, then, an auto-repeat key will generate the following sequence of events:</p> + +<ol> + <li><code>keydown</code></li> + <li><code>keypress</code></li> + <li><<repeating until the user releases the key>></li> + <li><code>keyup</code></li> +</ol> + +<p>In these environments, unfortunately, there's no way for web content to tell the difference between auto-repeating keys and keys that are just being pressed repeatedly.</p> + +<h4 id="Auto-repeat_handling_prior_to_Gecko_4.0">Auto-repeat handling prior to Gecko 4.0</h4> + +<p>Before Gecko 4.0 {{geckoRelease('4.0')}}, keyboard handling was less consistent across platforms.</p> + +<dl> + <dt>Windows</dt> + <dd>Auto-repeat behavior is the same as in Gecko 4.0 and later.</dd> + <dt>Mac</dt> + <dd>After the initial keydown event, only keypress events are sent until the keyup event occurs; the inter-spaced keydown events are not sent.</dd> + <dt>Linux</dt> + <dd>The event behavior depends on the specific platform. It will either behave like Windows or Mac depending on what the native event model does.</dd> +</dl> + +<h2 id="Example">Example</h2> + +<pre class="brush: js"><!DOCTYPE html> +<html> +<head> +<script> +var metaChar = false; +var exampleKey = 16; + +function keyEvent(event) { + var key = event.keyCode || event.which; + var keychar = String.fromCharCode(key); + if (key == exampleKey) { + metaChar = true; + } + if (key != exampleKey) { + if (metaChar) { + alert("Combination of metaKey + " + keychar); + metaChar = false; + } else { + alert("Key pressed " + key); + } + } +} + +function metaKeyUp (event) { + var key = event.keyCode || event.which; + + if (key == exampleKey) { + metaChar = false; + } +} +</script> +</head> + +<body onkeydown="keyEvent(event)" onkeyup="metaKeyUp(event)"> +</body> +</html> +</pre> + +<h2 id="Specifications">Specifications</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + <tr> + <td>{{SpecName('DOM3 Events', '#interface-KeyboardEvent', 'KeyboardEvent')}}</td> + <td>{{Spec2('DOM3 Events')}}</td> + <td>Initial definition.</td> + </tr> + </tbody> +</table> + +<p>The <code>KeyboardEvent</code> interface specification went through numerous draft versions, first under DOM Events Level 2 where it was dropped as no consensus arose, then under DOM Events Level 3. This led to the implementation of non-standard initialization methods, the early DOM Events Level 2 version, {{domxref("KeyboardEvent.initKeyEvent()")}} by Gecko browsers and the early DOM Events Level 3 version, {{domxref("KeyboardEvent.initKeyboardEvent()")}} by others. Both have been superseded by the modern usage of a constructor: {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}.</p> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{CompatibilityTable}}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Chrome</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>constructor</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("31.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.char</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>.charCode</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>.code</code></td> + <td colspan="5" rowspan="1">See Browser compatibility of {{domxref("KeyboardEvent.code")}}.</td> + </tr> + <tr> + <td><code>.isComposing</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("31.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>.key</code></td> + <td colspan="5" rowspan="1">See Browser compatibility of {{domxref("KeyboardEvent.key")}}.</td> + </tr> + <tr> + <td><code>.keyCode</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>.locale</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>.location</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("15.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>.repeat</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("28.0")}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>.which</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>.getModifierState()</code></td> + <td colspan="5" rowspan="1">See Browser compatibility of {{domxref("KeyboardEvent.getModifierState")}}</td> + </tr> + <tr> + <td><code>.initKeyboardEvent()</code></td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + <td>{{CompatNo}}<sup>[2]</sup></td> + <td>{{CompatIE("9.0")}}<sup>[3]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}<sup>[1]</sup></td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td>constructor</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("31.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.char</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.charCode</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.code</code></td> + <td colspan="5" rowspan="1">See Browser compatibility of {{domxref("KeyboardEvent.code")}}.</td> + </tr> + <tr> + <td><code>.isComposing</code></td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile("31.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>.key</code></td> + <td colspan="6">See Browser compatibility table of {{domxref("KeyboardEvent.key")}}.</td> + </tr> + <tr> + <td><code>.keyCode</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.locale</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.location</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("15.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.repeat</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatGeckoMobile("28.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.which</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + <tr> + <td><code>.getModifierState()</code></td> + <td colspan="5" rowspan="1">See Browser compatibility of {{domxref("KeyboardEvent.getModifierState")}}</td> + </tr> + <tr> + <td><code>.initKeyboardEvent()</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] The arguments of <code>initKeyboardEvent()</code> of WebKit and Blink's are different from the definition in DOM Level 3 Events. The method is: <code>initKeyboardEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString keyIndentifierArg, in number locationArg, in boolean ctrlKeyArg, in boolean altKeyArg, in boolean shiftKeyArg, in boolean metaKeyArg, in boolean altGraphKeyArg)</code></p> + +<p>[2] Gecko won't support <code>initKeyboardEvent()</code> because supporting it completely breaks feature detection of web applications. See {{Bug(999645)}}.</p> + +<p>[3] The argument of <code>initKeyboardEvent()</code> of IE is different from the definition in DOM Level 3 Events. The method is: <code>initKeyboardEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString keyArg, in number locationArg, in DOMString modifierListArg, in boolean repeatArt, in DOMString locationArg)</code>. See <a href="http://msdn.microsoft.com/en-us/library/ie/ff975297%28v=vs.85%29.aspx">document of <code>initKeyboardEvent()</code> in MSDN</a>.</p> + +<p><a href="http://www.howtocreate.co.uk/tutorials/javascript/domevents#domevld1">[4]</a> Note that manually firing an event does <em>not</em> generate the default action associated with that event. For example, manually firing a key event does not cause that letter to appear in a focused text input. In the case of UI events, this is important for security reasons, as it prevents scripts from simulating user actions that interact with the browser itself.</p> |