キーボード API

Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。

キーボード API は、ブラウザーを実行している端末に取り付けられている物理キーボードを操作するためのメソッドを提供します。

いくつかの機能を提供します。「キーボードマッピング」は、キーボードの特定の物理キーによって生成された文字列を取得するためのインターフェイスを提供し、そのキーをユーザーに正しく識別させます。「キーボードロック」は、通常ユーザーエージェントやオペレーティングシステムによって予約されているキーを、ウェブページがキャプチャできるようにします。キーボード API の使用目的は、ゲームやリモートアクセスアプリなど、全画面の没入感を提供するウェブアプリケーションです。

概念と使用方法

キーボードマッピング

物理的なキーボードでは、 code 属性は押されたキーの物理的な位置に、 key 属性はキーボードの物理的な位置でキーを押したときに生成される文字列になります。 key の値はキーボードのロケール（'en-US' など）、レイアウト（'QWERTY' など）、修飾キーの状態（Shift、Control など）に影響されます。歴史的に、その情報を取得する方法はありませんでした。

キーボードマップ API は、 Keyboard インターフェイスと KeyboardLayoutMap インターフェイスを通して、特定のキー押下によって生成された文字列を取得する方法を提供します。 Keyboard インターフェイスは navigator.keyboard からアクセスします。 Keyboard は Keyboard.getLayoutMap メソッドを提供し、コードをキーに変換するためのメンバーを含む KeyboardLayoutMap オブジェクトで解決するプロミスを返します。有効なコード値のリストは、 UI Events KeyboardEvent code Values 仕様の Writing System Keys の節にあります。

次の例は、英語の QWERTY キーボードで W と書かれたキーに関連する場所固有またはレイアウト固有の文字列を取得する方法を示しています。

js
if (navigator.keyboard) {
  const keyboard = navigator.keyboard;
  keyboard.getLayoutMap().then((keyboardLayoutMap) => {
    const upKey = keyboardLayoutMap.get("KeyW");
    window.alert(`Press ${upKey} to move up.`);
  });
} else {
  // ここで何かを行う
}

キーボードロック

リッチで双方向的なウェブページ、ゲーム、リモートストリーミングの体験では、全画面表示モード中に特別なキーやキーボードショートカットにアクセスする必要があることがよくあります。このようなキーやキーの組み合わせの例には、Escape、Alt+Tab、Ctrl+N などがあります。これらのキーとキーの組み合わせは、通常、次の例に示すように、ユーザーエージェントまたは基礎となるオペレーティングシステムによってキャプチャされます。

W、A、S、D の各キーをキャプチャするには、それぞれのキーのキーコード属性値を含むリストで lock() を呼び出します。

navigator.keyboard.lock(["KeyW", "KeyA", "KeyS", "KeyD"]);

これは、キーを押したときにどの修飾キーが使われたかに関係なく、これらのキーを捕捉します。標準的なアメリカ合衆国の QWERTY 配列と仮定すると、 KeyW を登録することで、W、Shift+W、Control+W、Control+Shift+W、およびその他のすべての修飾キーと W の組み合わせが確実にアプリに送信されます。 KeyA、KeyS、KeyD についても同様です。

システムキーの書き込み

Keyboard.lock と KeyboardLayoutMap インターフェイスの様々なメソッドに渡されるコードを「システムキーの書き込み」と呼びます。

物理キーは現在のロケールやキーボードレイアウトによって意味が変わるため、 Writing System Keys は UI Events KeyboardEvent code Values 仕様の Writing System Keys の章で定義されています。これらのキーを以下に示します。青いキーはすべての標準的なキーボードにありますが、緑のキーは一部のキーボードにしかありません。