JavaScript 的 KeyboardEvent.code 欄位是瀏覽器回報的識別碼,用來表示鍵盤上某個按鍵的實體位置,而且在不同的鍵盤佈局與修飾鍵狀態下都保持穩定。當開發者搜尋「我的汽車鑰匙的代碼」時,他們幾乎總是指這個屬性,而不是刻在金屬汽車鑰匙胚上的號碼——這是兩個截然不同的問題。真正的汽車鑰匙會在鑰匙頭上刻有切割代碼,由經銷商記錄,或由鎖匠保存,這個實體代碼會由鎖匠或經銷商的資料庫與點火鎖芯進行比對。相對地,網頁開發者問的「汽車鑰匙」問題,通常指向一個快捷鍵處理程式、遊戲輸入,或是需要知道使用者按下哪個實體按鍵的無障礙控制項。這個區別很重要,因為 KeyboardEvent.code 會回傳像 KeyW、Digit2、ArrowLeft 或 NumpadEnter 這類值,而 KeyboardEvent.key 則會回傳該實體位置在套用佈局與 Shift 之後所產生的內容——例如 2 對應 @,或是 ArrowLeft 對應其命名動作。JavaScript 按鍵代碼查詢工具的設計目的,就是從單一聚焦的 keydown 事件中並列顯示這兩個欄位,讓你不必再猜測,直接檢查瀏覽器實際送出的精確值。
JavaScript 按鍵代碼查詢工具實際擷取什麼
這個工具在一個刻意聚焦的擷取區域內,只監聽一個 keydown 事件,然後呈現開發者在快捷鍵處理程式、遊戲輸入、無障礙控制項,以及輸入診斷中最常需要的值。邊框區域以外所輸入的內容不會被觀察,不會安裝全域監聽器,也不會保留任何事件紀錄——只有最新一個事件會保存在 React 狀態中,直到頁面變更或重新載入。這讓這個工具在日常除錯時保持安全,而不會洩漏密碼、復原碼或其他機密資料,因為這個頁面從來不會把按鍵上傳到伺服器;擷取路徑中完全沒有伺服器往返。
你可以按下字母、數字、導覽鍵、修飾鍵、功能鍵或數字鍵盤按鍵,然後立即看到 key、code、location、作用中的修飾鍵、repeat 旗標、composing 旗標,以及舊式的數值 keyCode。擷取區域保有鍵盤可存取性,因此 Tab 可以移開焦點而不是把你困住,而其他按鍵只在擷取目標處於聚焦狀態時才會失去其預設動作——在檢查期間,Space 和方向鍵不會捲動頁面。
如何使用 JavaScript 按鍵代碼查詢工具檢查任何按鍵
下列四步驟工作流程對應此工具經驗證的操作步驟。這是釐清爭議最快的做法——無論是某個按鍵回報的是 KeyW 還是 KeyA、某個佈局產生的是 2 還是 @,或是 keyCode 是否能回傳任何有意義的值。
- 點擊或用 Tab 切換到有邊框的擷取區域。這個區域有可見的邊框,讓你在按下任何按鍵前能確認焦點。刻意讓聚焦於其他頁面元素時關閉擷取功能,這樣一般打字就不受影響。
- 按下你想檢查的按鍵或組合鍵。單按一次即可。按住按鍵會產生額外的事件,並帶有 repeat: true;而按下死鍵會產生一個 composing: true 的事件,接著才是組合後的字元——這兩者對 IME 與自動重複測試都很有用。
- 以 key 判讀語意、以 code 判讀實體位置,然後檢視 location 與修飾鍵。在美式佈局下,同一個實體按鍵在未搭配修飾鍵時回報 2,在按住 Shift 時回報 @,但 code 欄位會保持 Digit2。location 會告訴你這個 Enter 是來自主鍵盤、數字鍵盤,還是位於特定側邊的 Control 或 Alt。
- 只把 JSON 當作診斷用途複製,並在實際的目標瀏覽器與佈局上進行測試。格式化後的 JSON 紀錄對於錯誤回報或本機測試固定資料很方便,但單一的瀏覽器內檢查無法取代對你功能所支援的實際佈局、作業系統、瀏覽器、輔助技術與輸入法的相容性測試。
key、code 與事件其他欄位之間的關係
兩個最重要的欄位回答不同的問題,而擷取紀錄中的其他欄位則補齊了會在正式環境中困擾處理程式的邊界情況。下表整理了 W3C UI Events 規範在「語意」與「實體位置」之間所做的區分。
| 問題 | key | code |
|---|---|---|
| 反映目前的鍵盤佈局嗎? | 是 | 否 |
| 按住 Shift 時會改變嗎? | 是(例如 2 → @) | 否(保持 Digit2) |
| 識別一個實體按鍵位置嗎? | 否 | 是(例如 KeyW、Digit2) |
| 適合用於以字元為基礎的快捷鍵嗎? | 是 | 否 |
| 適合用於與佈局無關的快捷鍵(例如 WASD 移動)嗎? | 否 | 是 |
location 會區分同一個邏輯按鍵的標準、左側、右側與數字鍵盤版本——這對 Shift、Control、Alt、Meta、Enter 以及數字鍵來說很重要,因為在真實鍵盤上,每一個按鍵都可能出現在不只一個位置。修飾鍵清單只反映目前事件中所包含的修飾鍵狀態,而不是使用者按下過所有按鍵的全域歷史紀錄。當作業系統或瀏覽器在使用者按住按鍵時反覆送出 keydown 事件,repeat 就會變成 true——當你想在遊戲或捲動處理程式中限制自動重複時,這很有用。composing 表示輸入法或死鍵序列可能仍在產生文字,這是最強烈的訊號,告訴你快捷鍵處理程式應該等到組合結束後再動作。
在正式程式碼中於 key、code 與 keyCode 之間做選擇
讓欄位對應到你功能實際在問的問題。下表濃縮了 MDN 針對 KeyboardEvent.keyCode 所記載的實務建議,以及 W3C UI Events 對 key 與 code 的定義。
| 情境 | 建議欄位 |
|---|---|
| 偵測 Ctrl+S 以存檔,無論佈局為何 | code(例如 KeyS)加上修飾鍵檢查 |
| 在遊戲中使用 WASD 移動,而使用者佈局可能不是 QWERTY | 搭配 location 確認的 code |
| 區分數字鍵盤 Enter 與主鍵盤 Enter | 搭配 location 的 code(或 key) |
| 擷取文字欄位中輸入的字元 | key(並盡可能使用 input 事件) |
| 等待 IME 組合完成 | key 加上 composing 旗標 |
| 診斷仍會讀取 keyCode 的舊式程式庫 | keyCode 只能作為診斷用途,絕不能用於新程式碼 |
這個工具顯示 keyCode 僅用於相容性診斷。UI Events 並未為它定義可靠的現代值,MDN 將其標示為已棄用且與實作相關,而且可列印按鍵的行為多年來在不同瀏覽器與佈局之間一直有所差異。新程式碼應使用 key 或 code,並搭配針對特定功能的測試。請勿從 keyCode 推斷 ASCII、Unicode 或所輸入的字元:回傳值為零不一定代表沒有按鍵——它也可能代表舊式屬性在該瀏覽器或佈局上無法識別被按下的按鍵。
限制、行動裝置鍵盤與真實裝置測試
瀏覽器保留的快捷鍵、作業系統快捷鍵、無障礙技術、密碼管理程式、遠端桌面與輸入法,都可能在我們的頁面看到事件之前就先行攔截,因此在安靜的本機瀏覽器中運作的處理程式,可能在正式環境中默默地失效。行動裝置的虛擬鍵盤可能會暴露較少的 code 值,因為根本沒有實體按鍵位置可以回報——軟體鍵盤的 code 欄位可能是空的,或只是一個粗略的標籤。輸入法在序列進行中會觸發 composing: true,因此任何會變更文件狀態的快捷鍵,都應該延後到組合結束後再執行。
對自動化測試來說,請仔細建構 KeyboardEvent 固定資料,因為合成事件並非受信任的使用者輸入,且未必能重現原生平台行為。一組由八個標準事件衍生的精簡固定資料,就已足以涵蓋字母、加上 Shift 的數字、左與右 Alt、數字鍵盤 Enter,以及死鍵組合,而四個獨特的 location 標籤則可以分別獨立斷言。即使有了良好的固定資料,真實裝置仍是最終的相容性把關:請測試你功能所支援的確切佈局、作業系統、瀏覽器、輔助技術與 IME。務必為重要的快捷鍵提供可點擊的替代控制項、記錄已知的衝突,絕對不要讓單一實體鍵盤佈局成為完成關鍵動作的唯一方式。
因為擷取區域只在本機保留最新一個事件,你可以隨意重複執行任何檢查,而不會在伺服器上留下任何紀錄——JavaScript 按鍵代碼查詢工具的存在,只是為了讓你已經能在 DevTools 中讀取的屬性讀取起來更快速,並提供一份具有佈局感知的紀錄,讓你可以直接貼進錯誤回報中。
如果你在權衡選項,JavaScript 中常見的正規表示式模式:權杖參考對此有詳細說明。
如果你在權衡選項,如何在 JavaScript 中檢查正規表示式模式對此有詳細說明。