这篇翻译不完整。请帮忙从英语翻译这篇文章。
KeyboardEvent
对象描述了键盘的交互方式。 每个事件都描述了一个按键(Each event describes a key);事件类型keydown
, keypress
与 keyup
可以确定是哪种事件在活动。
KeyboardEvent
表示刚刚发生在按键上的事情。 当你需要处理文本输入的时候,使用 HTML5 input
事件代替。例如,用户使用手持系统如平板电脑输入时, 按键事件可能不会触发。构造器
KeyboardEvent()
- 创建一个
KeyboardEvent
对象。
方法
本接口同样会继承对象父代的方法, UIEvent
和 Event
。
KeyboardEvent.getModifierState()
- 返回一个
Boolean
,表示在事件创建时,修改键如Alt , Shift, Ctrl, Meta等是否按下。 KeyboardEvent.initKeyEvent()
- 初始化一个
KeyboardEvent
对象。Gecko 浏览器从来没有实现过本方法,其曾经使用过KeyboardEvent.initKeyboardEvent()
方法,但是以后大概都不会再使用。 现在的标准方式是使用KeyboardEvent()
构造器。 KeyboardEvent.initKeyboardEvent()
- 初始化一个
KeyboardEvent
对象。Gecko 浏览器从来没有实现过本方法,其曾经使用过KeyboardEvent.initKeyEvent()
方法,但是以后大概都不会再使用。 现在的标准方式是使用KeyboardEvent()
构造器。
属性
本接口同样会继承对象父代的属性, UIEvent
和 Event
。
KeyboardEvent.altKey
只读- Returns a
Boolean
that istrue
if the Alt ( Option or ⌥ on OS X) key was active when the key event was generated. KeyboardEvent.char
只读- Returns a
DOMString
representing the character value of the key. If the key corresponds to a printable character, this value is a non-empty Unicode string containing that character. If the key doesn't have a printable representation, this is an empty string.Note: If the key is used as a macro that inserts multiple characters, this attribute's value is the entire string, not just the first character.Warning: This has been dropped from DOM Level 3 Events. This is supported only on IE9+. KeyboardEvent.charCode
只读- Returns a
Number
representing the Unicode reference number of the key; this attribute is used only by thekeypress
event. For keys whosechar
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.Warning: This attribute is deprecated; you should useKeyboardEvent.key
instead, if available. KeyboardEvent.code
只读- Returns a
DOMString
with the code value of the key represented by the event. KeyboardEvent.ctrlKey
只读- Returns a
Boolean
that istrue
if the Ctrl key was active when the key event was generated. KeyboardEvent.isComposing
只读- Returns a
Boolean
that istrue
if the event is fired between aftercompositionstart
and beforecompositionend
. KeyboardEvent.key
只读- Returns a
DOMString
representing the key value of the key represented by the event. KeyboardEvent.keyCode
只读- Returns a
Number
representing a system and implementation dependent numerical code identifying the unmodified value of the pressed key.Warning: This attribute is deprecated; you should useKeyboardEvent.key
instead, if available. KeyboardEvent.keyIdentifier
只读- This property is non-standard and has been deprecated in favor of
KeyboardEvent.key
. It was part of an old version of DOM Level 3 Events. KeyboardEvent.keyLocation
只读- This is a non-standard deprecated alias for
KeyboardEvent.location
. It was part of an old version of DOM Level 3 Events. KeyboardEvent.locale
只读- Returns a
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.Note: 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. KeyboardEvent.location
只读- Returns a
Number
representing the location of the key on the keyboard or other input device. KeyboardEvent.metaKey
只读- Returns a
Boolean
that istrue
if the Meta key (on Mac keyboards, the ⌘ Command key; on Windows keyboards, the Windows key (⊞)) was active when the key event was generated. KeyboardEvent.repeat
只读- Returns a
Boolean
that istrue
if the key is being held down such that it is automatically repeating. KeyboardEvent.shiftKey
只读- Returns a
Boolean
that istrue
if the Shift key was active when the key event was generated. KeyboardEvent.which
只读- Returns a
Number
representing a system and implementation dependent numeric code identifying the unmodified value of the pressed key; this is usually the same askeyCode
.Warning: This attribute is deprecated; you should useKeyboardEvent.key
instead, if available.
注意事项
There are keydown
, keypress
, and keyup
events. For most keys, Gecko dispatches a sequence of key events like this:
- When the key is first depressed, the
keydown
event is sent. - If the key is not a modifier key, the
keypress
event is sent. - When the user releases the key, the
keyup
event is sent.
特殊情况
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 keydown
and keyup
events. Note that on Linux, Firefox 12 and earlier also dispatched the keypress
event for these keys.
On Mac, however, Caps Lock dispatches only the keydown
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 keypress
event. This inconsistent behavior is a bug; see bug 602812.
自动重复处理
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:
keydown
keypress
keydown
keypress
- <>
keyup
This is what the DOM Level 3 specification says should happen. There are some caveats, however, as described below.
Auto-repeat on some GTK environments such as Ubuntu 9.4
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:
keydown
keypress
keyup
keydown
keypress
keyup
- <>
keyup
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.
Auto-repeat handling prior to Gecko 5.0
Before Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2), keyboard handling was less consistent across platforms.
- Windows
- Auto-repeat behavior is the same as in Gecko 4.0 and later.
- Mac
- After the initial keydown event, only keypress events are sent until the keyup event occurs; the inter-spaced keydown events are not sent.
- Linux
- The event behavior depends on the specific platform. It will either behave like Windows or Mac depending on what the native event model does.
示例
<!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>
规范
Specification | Status | Comment |
---|---|---|
Document Object Model (DOM) Level 3 Events Specification KeyboardEvent |
Working Draft | Initial definition. |
The KeyboardEvent
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, KeyboardEvent.initKeyEvent()
by Gecko browsers and the early DOM Events Level 3 version, KeyboardEvent.initKeyboardEvent()
by others. Both have been superseded by the modern usage of a constructor: KeyboardEvent()
.
浏览器支持
More compatibility data is available on other pages:
.code
- See Browser compatibility ofKeyboardEvent.code
..key
- See Browser compatibility ofKeyboardEvent.key
..getModifierState()
- See Browser compatibility ofKeyboardEvent.getModifierState
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|
Basic support | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
constructor | (Yes) | 31.0 (31.0) | 未实现 | (Yes) | ? |
.char |
未实现 | 未实现 | 9 | 未实现 | 未实现 |
.charCode |
(Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
.isComposing |
未实现 | 31.0 (31.0) | 未实现 | 未实现 | 未实现 |
.keyCode |
(Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
.locale |
未实现 | 未实现 | (Yes) | 未实现 | 未实现 |
.location |
(Yes) | 15.0 (15.0) | (Yes) | 未实现 | 未实现 |
.repeat |
(Yes) | 28.0 (28.0) | (Yes) | 未实现 | 未实现 |
.which |
(Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
.initKeyboardEvent() |
(Yes)[1] | 未实现[2] | 9.0[3] | ? | (Yes)[1] |
Feature | Android | Firefox Mobile (Gecko) | IE Phone | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|
Basic support | ? | (Yes) | ? | ? | ? |
constructor | ? | 31.0 (31.0) | ? | ? | ? |
.char |
? | 未实现 | ? | ? | ? |
.charCode |
? | (Yes) | ? | ? | ? |
.isComposing |
未实现 | 31.0 (31.0) | 未实现 | 未实现 | 未实现 |
.keyCode |
? | (Yes) | ? | ? | ? |
.locale |
? | 未实现 | ? | ? | ? |
.location |
? | 15.0 (15.0) | ? | ? | ? |
.repeat |
? | 28.0 (28.0) | ? | ? | ? |
.which |
? | (Yes) | ? | ? | ? |
.initKeyboardEvent() |
? | 未实现 | ? | ? | ? |
[1] The arguments of initKeyboardEvent()
of WebKit and Blink's are different from the definition in DOM Level 3 Events. The method is: initKeyboardEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString keyIdentifierArg, in number locationArg, in boolean ctrlKeyArg, in boolean altKeyArg, in boolean shiftKeyArg, in boolean metaKeyArg, in boolean altGraphKeyArg)
[2] Gecko won't support initKeyboardEvent()
because supporting it completely breaks feature detection of web applications. See bug 999645.
[3] The argument of initKeyboardEvent()
of IE is different from the definition in DOM Level 3 Events. The method is: 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)
. See document of initKeyboardEvent()
in MSDN.
[4] Note that manually firing an event does not 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.