KeyboardEvent

翻譯不完整。請協助 翻譯此英文文件

KeyboardEvent objects 用來詳述使用者和網頁之間,經由鍵盤產生的互動。每個事件(event)都記錄著一次鍵盤動作。事件類型(keydownkeypress 和 keyup)用來表示鍵盤執行哪種動作。

注意: KeyboardEvent 僅顯示在鍵盤上發生的事。當你需要進行文字輸入的操作,請使用 HTML5 input event 代替 KeyboardEvent 。舉例來說,當使用者在手寫系統,例如平板電腦,輸入文字時,並不會啟動 key events 。

Constructor

KeyboardEvent()
建立一 KeyboardEvent object。

Methods

本介面( interface)亦繼承其父, UIEventEvent ,的 methods

KeyboardEvent.getModifierState()
回傳一 Boolean。用來表示當事件建立時,修飾鍵(例如 Alt、 Shift、 Ctrl、或是 Meta) 是否是按下的。
KeyboardEvent.initKeyEvent()
初始化一個 KeyboardEvent object。這個 method 只有 Gecko 有在使用(其他瀏覽器是使用 KeyboardEvent.initKeyboardEvent()),並且不應該再繼續使用。現代的標準規範是使用 KeyboardEvent() constructor。
KeyboardEvent.initKeyboardEvent()
初始化一個 KeyboardEvent object。 Gecko 從未實作過該 method (Gecko 是使用 KeyboardEvent.initKeyEvent()) ,並且不應該再繼續使用。現代的標準規範是使用 KeyboardEvent() constructor。

Properties

本介面( interface)亦繼承其父,UIEventEvent ,的 properties 。

KeyboardEvent.altKey Read only
一個 Boolean 。用來表示在事件建立時, Alt (OS X 中是 Option ) 鍵是否執行中。
KeyboardEvent.char Read only
一個 DOMString ,返回鍵盤對應的字符。若是該鍵對應一個實際的字符,則其值為對應該字符的一個非空的 Unicode 字串;若沒對應的話,則返回一個空字串。
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.
警告: 在 DOM Level 3 Events ,該 propertie 已被移除。現在只有 IE9+ 支持它。
KeyboardEvent.charCode Read only
Returns a Number representing the Unicode reference number of the key; this attribute is used only by the keypress event. For keys whose char 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.
警告: 此 attribute 已被淘汰。如果可以,建議使用 KeyboardEvent.key
KeyboardEvent.code Read only
一個 DOMString 。返回事件對應的按鍵的代碼。
KeyboardEvent.ctrlKey Read only
一個 Boolean 。用來表示在事件建立時, Ctrl 鍵是否執行中。
KeyboardEvent.isComposing Read only
一個 Boolean 。用來表示其觸發時間是否在 compositionstartcompositionend 之間。
KeyboardEvent.key Read only
一個 DOMString ,用來事件對應的按鍵的值(key value)。
KeyboardEvent.keyCode  Read only
Returns a Number representing a system and implementation dependent numerical code identifying the unmodified value of the pressed key.
警告: 此 attribute 已被淘汰。如果可以,建議使用KeyboardEvent.key
KeyboardEvent.locale Read only
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 Read only
Returns a Number representing the location of the key on the keyboard or other input device.
KeyboardEvent.metaKey Read only
Returns a Boolean that is true if the Meta (on Mac keyboards, the ⌘ Command key; on Windows keyboards, the Windows key ()) key was active when the key event was generated.
KeyboardEvent.repeat Read only
Returns a Boolean that is true if the key is being held down such that it is automatically repeating.
KeyboardEvent.shiftKey Read only
Returns a Boolean that is true if the Shift key was active when the key event was generated.
KeyboardEvent.which Read only
Returns a Number representing a system and implementation dependent numeric code identifying the unmodified value of the pressed key; this is usually the same as keyCode.
警告: 此 attribute 已被淘汰。如果可以,建議使用 KeyboardEvent.key

注意

KeyboardEvent 有 keydownkeypresskeyup 三種事件。對大多數的按鍵而言, Gecko 觸發事件的順序如下:

  1. 當按鍵按下時,會送出 keydown event 。
  2. 當按鍵不是特殊鍵( modifier key),例如CtrlAlt……等等,會送出 keypress event 。
  3. 當按鍵放開時,會送出 keyup event 。

特殊狀況

某些按鍵,例如 Caps Lock 、 Num Lock 和 Scroll Lock 能切換鍵盤上的 LED 燈。在 Windows 和 Linux 系統上,這些按鍵只會觸發 keydown 和 keyup 事件。但是 Linux 上的 Firefox 12 或更早的版本亦會觸發 keypress 事件。

而在 Mac 電腦則不同, Caps Lock 只會觸發 keydown 事件;而 Num Lock 則是只有舊版的 Mac 電腦(2007 或之前的版本)才有,現在的 Mac 即便使用外部鍵盤也不支援  Num Lock 。雖說舊版的 Mac 電腦支援 Num Lock 鍵,但 Num Lock  並不會執行任何 KeyboardEvent;而 Gecko 瀏覽器在特殊情況(外接一個有 F14 的鍵盤)下能支援 Scroll Lock ,但是它會產生 keypress 事件。這個異常狀態是個 bug ,詳情可參考 bug 602812

自動迴圈(Auto-Repeat )的執行

當按鍵按下去不放時,它會開始一個自動迴圈。並導致觸發一系列的相似事件,如下所示:

  1. keydown
  2. keypress
  3. keydown
  4. keypress
  5. (不斷重複,直到使用者放開按鍵)
  6. keyup

在 DOM Level 3 說明書有提及這問題是會發生的。其中所存在的問題如下說明:

部分 GTK 環境,例如 Ubuntu 9.4 ,的自動迴圈

部分的 GTK-based 環境之中,自動迴圈在發生的過程中會自動觸發電腦本機的 key-up 事件。然而,對 Gecko 而言,並沒有方法可以分辨使用者重複點擊按鍵與自動迴圈(按鍵按住不放)的差異。在這類的環境下,按鍵按住不放會重複執行下列事件:

  1. keydown
  2. keypress
  3. keyup
  4. keydown
  5. keypress
  6. keyup
  7. (不斷重複,直到使用者放開按鍵)
  8. keyup

不幸地,在這些環境之下,web content 亦沒有方法告訴使用者重複點擊按鍵與自動迴圈的差異。

Gecko 5.0 以前的自動迴圈

Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2) 以前,在不同平台上,鍵盤的處理與現在相比較不統一。

Windows
自動迴圈的結果與 Gecko 4.0 或更新的版本類似
Mac
在第一個 keydown 執行後,僅執行 keypress 事件,一直到案件放開(即送出 keyup 事件指令),過程中不會送出任何 keydown 事件。
Linux
鍵盤事件的執行根據平台不同而有所不同。它有可能表現得像是 Windows 也有可能像 Mac ,這取決於本地的事件模型(native event model)是如何執行的。

範例

<!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
The definition of 'KeyboardEvent' in that specification.
Working Draft 原始定義

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:

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support (Yes) (Yes) (Yes) (Yes) (Yes)
constructor (Yes) 31.0 (31.0) Not supported (Yes) ?
.char Not supported Not supported (Yes) Not supported Not supported
.charCode (Yes) (Yes) (Yes) (Yes) (Yes)
.code See Browser compatibility of KeyboardEvent.code.
.isComposing Not supported 31.0 (31.0) Not supported Not supported Not supported
.key See Browser compatibility of KeyboardEvent.key.
.keyCode (Yes) (Yes) (Yes) (Yes) (Yes)
.locale Not supported Not supported (Yes) Not supported Not supported
.location (Yes) 15.0 (15.0) (Yes) Not supported Not supported
.repeat (Yes) 28.0 (28.0) (Yes) Not supported Not supported
.which (Yes) (Yes) (Yes) (Yes) (Yes)
.getModifierState() See Browser compatibility of KeyboardEvent.getModifierState
.initKeyboardEvent() (Yes)[1] Not supported[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 ? Not supported ? ? ?
.charCode ? (Yes) ? ? ?
.code See Browser compatibility of KeyboardEvent.code.
.isComposing Not supported 31.0 (31.0) Not supported Not supported Not supported
.key See Browser compatibility table of KeyboardEvent.key.
.keyCode ? (Yes) ? ? ?
.locale ? Not supported ? ? ?
.location ? 15.0 (15.0) ? ? ?
.repeat ? 28.0 (28.0) ? ? ?
.which ? (Yes) ? ? ?
.getModifierState() See Browser compatibility of KeyboardEvent.getModifierState
.initKeyboardEvent() ? Not supported ? ? ?

[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 keyIndentifierArg, 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.

文件標籤與貢獻者

標籤: 
 此頁面的貢獻者: Shiyou
 最近更新: Shiyou,