JavaScript 按鍵代碼查詢工具 是一個專注的診斷頁面，將單一 keydown 事件解碼為開發人員實際用來分支判斷的標準 KeyboardEvent 欄位。當你點擊進入帶有邊框的擷取區域並按下按鍵時，頁面會讀取瀏覽器傳遞給該元素的事件，並顯示 key、code、location、作用中修飾鍵列表、repeat 旗標、composition 旗標，以及舊式的數值 keyCode。頁面只會在暫存的記憶體 React 狀態中保留該單一事件，將其顯示為結構化記錄，並讓你以格式化的 JSON 複製下來，供錯誤報告或本機測試資料使用。在擷取區域之外輸入的內容不會被觀察，重新載入後不會保留任何事件歷史紀錄，也不會有網路請求將事件資料帶離頁面，這對於一個唯一職責就是讓 KeyboardEvent 變得可讀的工具來說，是合適的設計。
更困難的問題是這些欄位各自實際代表什麼意思，因為欄位名稱以令人困惑的方式重疊。key 和 code 這兩個欄位都描述單一按鍵動作，但回答的是不同的問題。第三個欄位 location 則指出按鍵在實體鍵盤上的位置。修飾鍵列表、repeat 旗標和 composition 旗標描述的是該事件的周圍狀態，而不是按鍵本身。舊式的 keyCode 欄位會出現在記錄的底部並附帶警告，因為 UI Events 規格並未為它定義可靠的現代值，而 MDN 也將其標記為已棄用。本文將逐一說明每個欄位、它回答的問題，以及在哪些情況下它是分支判斷的正確選擇，並提供 W3C UI Events 規格與 MDN KeyboardEvent 參考文件的相關資料。
每個 KeyboardEvent 欄位實際回答的問題
KeyboardEvent 介面定義了幾個看起來可以互換、實際上回答不同問題的欄位。key、code 和 location 是最常被混淆的三個，因為它們各自命名的是同一按鍵的不同面向。本文接近結尾處的參考表格會將每個欄位對應到它回答的問題並提供實際範例，但先理解其設計意圖會有所幫助。
key 代表在套用當前鍵盤配置與修飾鍵狀態後所產生的意義。在美式配置下，同一個實體按鍵在未按 Shift 時回報 "2"，按住 Shift 時則回報 "@"。在德式配置下，同一個實體按鍵在未按 Shift 時回報 "2"，按住 Shift 時則回報不同的引號字元。由於 key 會跟隨使用者的配置與語言，因此對於應跟隨輸入字元或具名動作(例如 "Enter"、"Escape" 或 "ArrowUp")的快捷鍵來說，它是正確的欄位。綁定到 Ctrl+S 的儲存快捷鍵應該分支判斷 key，因為使用者思考的是字元和具名動作，而不是實體位置。
code 代表鍵盤上的實體按鍵位置，例如 "Digit2" 或 "KeyW"，通常在不同配置之間保持穩定。同一個實體 2 鍵在美式、德式、法式和日式配置下都會回報 "Digit2"，因為 code 繫結的是位置而非意義。code 是與配置無關的綁定(例如遊戲中的 WASD 移動、重新對應的控制介面，或是無論選擇何種語言都必須觸發的無障礙快捷鍵)的正確欄位。常見的錯誤是為移動控制分支判斷 key，然後釋出的版本在任何非 QWERTY 使用者上就會失效，因為 "W" 的意義只有在 W 鍵會產生該字母的配置下才會是 "W"。
location 用於區分按鍵的標準、左、右和數字鍵盤變體。W3C UI Events 規格指定了 DOM_KEY_LOCATION_STANDARD、DOM_KEY_LOCATION_LEFT、DOM_KEY_LOCATION_RIGHT 和 DOM_KEY_LOCATION_NUMPAD。Shift、Control、Alt、Meta、Enter 以及大多數數字鍵在完整的鍵盤上可能存在於多個位置，而針對「右側 Shift」的控制方案若不讀取 location，就無法區分這些變體。下面四步驟程序中描述的擷取流程會立即讓這個區別變得明顯。
如何以四個步驟在本機檢查按鍵
擷取流程刻意設計得很短，以避免悄悄記錄工作階段的機會。每當你開啟基於瀏覽器的按鍵代碼測試工具時，請使用這些步驟，並將同樣的檢查清單套用到你評估的任何競爭工具上。
- 點擊或以 Tab 切換到帶有邊框的擷取區域，使其元素成為作用中的鍵盤目標，並可從可見的焦點框確認。
- 按下你想要檢查的按鍵或組合鍵，例如 Shift + 2、Control + Alt + Enter、功能鍵或數字鍵盤數字。
- 比較 key(代表意義)與 code(代表實體位置)，然後檢視 location 與作用中的修飾鍵，以確認觸發的是哪一個變體。
- 僅將 JSON 作為診斷用途複製，並在正式發行前於真實的目標瀏覽器、配置、輸入法和輔助技術上進行測試。
步驟 3 是此工具價值的核心。key 欄位反映套用作用中配置與修飾鍵後所產生的字元，因此在美式配置下，同一個實體按鍵會依 Shift 狀態回報 2 或 @。code 欄位回報實體位置，例如 Digit2 或 KeyW，在不同配置間保持穩定。location 回報鍵盤上的變體，讓你明確綁定到「右側 Shift」或「數字鍵盤 Enter」而不會產生混淆。步驟 4 是一種紀律要求而非工具功能:在自動化測試中建立的合成 KeyboardEvent 資料並非可信的使用者輸入，且可能無法重現原生平台行為，因此在宣告快捷鍵完成之前，務必在真實硬體上進行確認。使用 JavaScript 按鍵代碼查詢工具的配套說明對應了此程序，並說明在將 JSON 記錄貼到錯誤報告之前應如何格式化。
事件周圍的修飾鍵、Repeat 與 Composition 旗標
有三個較小的欄位描述的是同一個 keydown 事件的周圍狀態，而不是按鍵本身。修飾鍵列表回報的是包含在事件中的狀態，而不是所有按下內容的全域歷史。即使兩個 Shift 鍵都處於按下狀態，觸發的按鍵仍會回報 "Shift" 為單一修飾鍵，因為該欄位描述的是此事件上的布林狀態而非計數。shiftKey、ctrlKey、altKey 和 metaKey 會反映在修飾鍵列表中，直接從事件讀取這些值比起自己跨處理程序追蹤按鍵狀態更為可靠。
當作業系統或瀏覽器在按住按鍵時發出重複的 keydown 事件，repeat 會變成 true。射擊遊戲中的自動射擊、文字編輯器，或持續按住的箭頭鍵，都會在第一個事件之後產生 repeat=true。在每次 keydown 上執行動作的快捷鍵處理程序通常應檢查 repeat 並忽略後續事件，否則按住的按鍵每秒將重新觸發動作數十次。repeat 值是此工具所顯示事件記錄的一部分，因此你可以確認自動重複是否符合預期，而不是憑猜測判斷。
composing 表示輸入法或死鍵組合可能正在產生文字。在日文 IME、韓文 IME，或使用死鍵的拉丁配置上，開始組合的 keydown 會回報 composing=true，而組合期間的後續事件會持續設定該旗標。在 keydown 上執行動作的快捷鍵處理程序通常應延後到 composing 翻回 false 之後，否則按下死鍵以輸入 "é" 可能會觸發儲存快捷鍵。composition 旗標是僅檢查 key 和 code 的處理程序最常遺漏的欄位之一，而診斷記錄會讓它的存在顯而易見。
keyCode 是舊式欄位，不是現代解答
舊式的數值 keyCode 欄位僅顯示用於相容性診斷。MDN 將 keyCode 標記為已棄用且與實作相依，而 W3C UI Events 規格並未為其定義可靠的現代值。可列印按鍵的行為多年來在瀏覽器和配置之間一直存在差異，值為零並不一定代表沒有對應的按鍵;它可能意味著舊式屬性無法識別你所按下的按鍵。新程式碼應在涉及意義時分支判斷 key，在涉及實體位置時分支判斷 code，並透過針對特定功能的測試來描述精確的快捷鍵。
請勿從 keyCode 推斷 ASCII、Unicode 或輸入字元。該欄位在 1990 年代晚期瀏覽器使用自家專有對應時曾有其用途，但從未標準化，現代處理程序沒有理由讀取它。此工具在記錄底部將其顯示並附帶警告，目的是讓你在遷移過程中確認舊式處理程序所看到的內容，而不是讓你據此撰寫新功能。配套的 MDN KeyboardEvent.keyCode 參考文件列出了相同的棄用說明，並解釋了使其在現代程式碼中不可靠的實作相依行為。
會影響此工具是否能解碼你的快捷鍵的限制
即使是純本機的診斷工具，也無法解碼瀏覽器從未傳遞的事件。瀏覽器保留的快捷鍵(例如 Ctrl+W、Cmd+Tab、Cmd+Space 和 Ctrl+Shift+Esc)可能會在任何頁面處理程序執行之前被瀏覽器或作業系統攔截，如 W3C UI Events 規格所述。輔助技術、密碼管理工具、遠端桌面用戶端和輸入法也會為了自身用途攔截按鍵，因此從未收到事件的頁面無法解碼任何事件。如果你在擷取區域內按下保留的快捷鍵而記錄沒有更新，表示瀏覽器保留了該事件而未傳遞它。
行動虛擬鍵盤可能會公開較少的 code 值，因為不存在實體按鍵位置。觸控鍵盤並未繫結到固定配置，因此行動裝置上的 code 經常回傳空字串或通用值，而實體鍵盤則會回傳 "KeyW" 或 "Digit2"。composition 旗標在螢幕 IME 上的行為也不同，在手機上測試不等同於在配備德式配置和註腳 IME 的筆記型電腦上測試。真實裝置與精確的目標配置始終是最終的相容性檢查，從此頁面複製的 JSON 記錄是起點，而非該檢查的替代品。
參考表：欄位、意義與範例值
| 欄位 | 回答的問題 | 範例值 | 用途 |
|---|---|---|---|
| key | 套用配置與修飾鍵後的意義 | "@" 或 "a" | 接在某個字元或具名動作後的快捷鍵 |
| code | 鍵盤上的實體按鍵位置 | "Digit2" 或 "KeyW" | WASD 移動、與配置無關的綁定 |
| location | 該按鍵在鍵盤上的實體位置 | standard、left、right、numpad 等變體 | 區分 Shift、Control、Alt、Meta、Enter 以及數字區的變體 |
| modifier list | 此事件中包含的修飾鍵狀態 | ["Shift"] 或 ["Control", "Alt"] | 確認按鍵觸發時哪些修飾鍵處於作用中 |
| repeat | 作業系統是否正在自動重複按鍵 | 按住按鍵期間為 true | 在快捷鍵處理程序中過濾自動重複 |
| composing | 是否有 IME 或死鍵正在產生文字 | 組字期間為 true | 將快捷鍵處理延後到組字結束 |
| keyCode | 舊式的數值識別碼，已棄用 | 依瀏覽器而異 | 僅用於相容性診斷 |
這份表格刻意採用定性描述。已棄用欄位中的 keyCode 值在不同瀏覽器與配置之間並不穩定，你在實際記錄中看到的任何數字都屬於實作相依，並非權威值。若需要感知配置的行爲，請使用 key;若需要實體綁定，請使用 code;若需要區分重複按鍵的變體，請使用 location。
本機診斷工具的隱私與信任
只從一個聚焦的擷取區域讀取單一事件的按鍵測試工具，攻擊面很小，這正是診斷工具該有的樣貌。該頁面只在有邊框的目標取得焦點時進行監聽，將最近一次事件保存在短暫的記憶體內 React 狀態中，且不會寫入 local storage、IndexedDB、cookie 或任何遠端端點。背景中沒有 service worker 在執行，不會要求剪貼簿權限，事件紀錄也不會在重新載入後保留。儘管內容留在本地，仍請避免輸入密碼、復原碼或其他機密資訊;鍵盤診斷工具永遠不需要機密內容，而「不要把機密貼進測試框中」這條規則適用於此類別的所有工具，不限於這一個。
如果瀏覽器型按鍵測試工具要求剪貼簿、麥克風或鍵盤權限，或者在你測試時 DevTools 顯示有 fetch、WebSocket 或 sendBeacon 呼叫夾帶事件資料，請換一套工具，不要繼續使用。正確的診斷頁面也應該是安靜的，因為瀏覽器已經把該工具所顯示的每個欄位都暴露給頁面上的每個腳本，而安全的工具只不過是選擇不對它們再多做任何事。請務必為必要的快捷鍵提供另一個可點擊的控制項、記錄與輔助技術或 IME 之間已知的衝突，並且絕不要讓單一實體鍵盤配置成為完成關鍵操作的唯一方式。