KeyboardEvent

建構函式

KeyboardEvent()

建立一個新的 KeyboardEvent 物件。

常量

KeyboardEvent 介面定義了以下常量。

鍵盤位置

以下常量標識按鍵事件源自鍵盤的哪個部分。它們以 KeyboardEvent.DOM_KEY_LOCATION_STANDARD 等方式訪問。

例項屬性

此介面還繼承其父級 UIEvent 和 Event 的屬性。

KeyboardEvent.altKey 只讀

返回一個布林值，如果生成按鍵事件時 Alt 鍵（macOS 上為 Option 或 ⌥ 鍵）處於活動狀態，則返回 true。

KeyboardEvent.code 只讀

返回一個字串，其中包含事件所代表的物理鍵的程式碼值。

警告： 這會忽略使用者的鍵盤佈局，因此如果使用者在 QWERTY 鍵盤佈局中按下 "Y" 位置的鍵（在主行上方一行的中間附近），這將始終返回 "KeyY"，即使使用者使用的是 QWERTZ 鍵盤（這意味著使用者期望一個 "Z"，所有其他屬性也將指示一個 "Z"）或 Dvorak 鍵盤佈局（使用者期望一個 "F"）。如果你想向用戶顯示正確的按鍵，可以使用 Keyboard.getLayoutMap()。

KeyboardEvent.ctrlKey 只讀

返回一個布林值，如果生成按鍵事件時 Ctrl 鍵處於活動狀態，則返回 true。

KeyboardEvent.isComposing 只讀

返回一個布林值，如果事件在 compositionstart 之後和 compositionend 之前觸發，則返回 true。

KeyboardEvent.key 只讀

返回一個字串，表示事件所代表的鍵的鍵值。

KeyboardEvent.location 只讀

返回一個數字，表示鍵盤或其他輸入裝置上按鍵的位置。標識位置的常量列表顯示在上面的鍵盤位置中。

KeyboardEvent.metaKey 只讀

返回一個布林值，如果生成按鍵事件時 Meta 鍵（Mac 鍵盤上的 ⌘ Command 鍵；Windows 鍵盤上的 Windows 鍵 (⊞)）處於活動狀態，則返回 true。

KeyboardEvent.repeat 只讀

返回一個布林值，如果按鍵被按住並自動重複，則返回 true。

KeyboardEvent.shiftKey 只讀

返回一個布林值，如果生成按鍵事件時 Shift 鍵處於活動狀態，則返回 true。

已廢棄的屬性

KeyboardEvent.charCode 已棄用 只讀

返回一個數字，表示鍵的 Unicode 參考號；此屬性僅由 keypress 事件使用。對於其 char 屬性包含多個字元的鍵，這是該屬性中第一個字元的 Unicode 值。在 Firefox 26 中，這會返回可列印字元的程式碼。

KeyboardEvent.keyCode 已棄用 只讀

返回一個數字，表示一個系統和實現相關的數字程式碼，用於標識按下的鍵的未修改值。

KeyboardEvent.keyIdentifier 非標準 已棄用 只讀

此屬性為非標準屬性，已棄用，建議改用 KeyboardEvent.key。它曾是 DOM Level 3 Events 舊版本的一部分。

例項方法

此介面還繼承了其父級 UIEvent 和 Event 的方法。

KeyboardEvent.getModifierState()

返回一個布林值，指示在建立事件時是否按下了修飾鍵，例如 Alt、Shift、Ctrl 或 Meta。

已廢棄的方法

KeyboardEvent.initKeyboardEvent() 已棄用

初始化一個 KeyboardEvent 物件。此方法現已棄用。您應該改用 KeyboardEvent() 建構函式。

事件

以下事件基於 KeyboardEvent 型別。在下面的列表中，每個事件都連結到該事件的 Element 處理程式的文件，該處理程式通常適用於所有接收者，包括 Element、Document 和 Window。

keydown

按鍵已被按下。

keyup

按鍵已被釋放。

廢棄事件

keypress 已棄用

通常會產生字元值的按鍵已被按下。此事件高度依賴於裝置且已廢棄。您不應使用它。

用法說明

有三種類型的鍵盤事件：keydown、keypress 和 keyup。對於大多數按鍵，Gecko 會按以下方式分發一系列按鍵事件：

1. 當第一次按下鍵時，會發送 keydown 事件。
2. 如果按鍵不是修飾鍵，則傳送 keypress 事件。
3. 當用戶釋放按鍵時，會發送 keyup 事件。

特殊情況

某些鍵會切換指示燈的狀態；這些鍵包括 Caps Lock、Num Lock 和 Scroll Lock 等鍵。在 Windows 和 Linux 上，這些鍵只分發 keydown 和 keyup 事件。

然而，macOS 事件模型的限制導致 Caps Lock 只分發 keydown 事件。Num Lock 在一些較舊的筆記型電腦型號（2007 年及更早型號）上受支援，但從那時起，macOS 即使在外部鍵盤上也不支援 Num Lock。在帶有 Num Lock 鍵的舊款 MacBook 上，該鍵不生成任何鍵事件。如果連線了帶 F14 鍵的外部鍵盤，Gecko 支援 Scroll Lock 鍵。在某些舊版本的 Firefox 中，此鍵會生成 keypress 事件；這種不一致的行為是 Firefox bug 602812。

自動重複處理

當按鍵被按下並按住時，它會開始自動重複。這會導致一系列事件被分發，類似於以下內容：

1. keydown
2. keypress
3. keydown
4. keypress
5. <<重複直到使用者釋放按鍵>>
6. keyup

這是 DOM Level 3 規範所說的應該發生的情況。然而，有一些注意事項，如下所述。

在某些 GTK 環境中自動重複，例如 Ubuntu 9.4

在某些基於 GTK 的環境中，自動重複會在自動重複期間自動分發原生按鍵抬起事件，並且 Gecko 無法區分重複的按鍵系列和自動重複。因此，在這些平臺上，自動重複鍵將生成以下事件序列：

1. keydown
2. keypress
3. keyup
4. keydown
5. keypress
6. keyup
7. <<重複直到使用者釋放按鍵>>
8. keyup

在這些環境中，不幸的是，Web 內容無法區分自動重複鍵和僅僅是重複按下的鍵。

示例

document.addEventListener("keydown", (event) => {
  const keyName = event.key;

  if (keyName === "Control") {
    // do not alert when only Control key is pressed.
    return;
  }

  if (event.ctrlKey) {
    // Even though event.key is not 'Control' (e.g., 'a' is pressed),
    // event.ctrlKey may be true if Ctrl key is pressed at the same time.
    alert(`Combination of ctrlKey + ${keyName}`);
  } else {
    alert(`Key pressed ${keyName}`);
  }
});

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

  // As the user releases the Ctrl key, the key is no longer active,
  // so event.ctrlKey is false.
  if (keyName === "Control") {
    alert("Control key was released");
  }
});

規範

KeyboardEvent 介面規範經歷了無數草案版本，首先在 DOM Events Level 2 中因未能達成共識而被放棄，然後是 DOM Events Level 3。這導致了非標準初始化方法的實現，早期 DOM Events Level 2 版本 KeyboardEvent.initKeyEvent() 由 Gecko 瀏覽器實現，以及早期 DOM Events Level 3 版本 KeyboardEvent.initKeyboardEvent() 由其他瀏覽器實現。兩者都已被現代建構函式 KeyboardEvent() 取代。

瀏覽器相容性

相容性說明

• 從 Firefox 65 開始，對於不可列印的鍵（Firefox bug 968056），不再觸發 keypress 事件，但 Enter 鍵以及 Shift + Enter 和 Ctrl + Enter 鍵組合除外（這些是為了跨瀏覽器相容性而保留的）。

另見

• KeyboardEvent.code.
• KeyboardEvent.key.
• KeyboardEvent.getModifierState()