キーボードロック

1. 導入

豊かにインタラクティブな Web サイト、ゲーム、およびリモート デスクトップ／アプリケーションのストリーミング体験は、 没入型のフルスクリーン体験を提供したい。そのためには、サイトは フルスクリーンモード中に、ナビゲーション、メニュー、またはゲーム機能に 使用できるよう、特別なキーやキーボードショートカットにアクセスする 必要がある。必要となる可能性があるキーの例としては、Escape、Alt+Tab、Cmd+`、および Ctrl+N がある。

既定では、これらのキーはブラウザーまたは基盤となるオペレーティング システムによって捕捉されるため、Web アプリケーションでは利用できない。 Keyboard Lock API は、OS によって許可される利用可能なすべてのキーを Web サイトが捕捉して使用できるようにする。

2. Keyboard Lock API

2.1. Navigator インターフェイス

partial interface Navigator {
  [SecureContext, SameObject] readonly attribute Keyboard keyboard;
};

2.2. Keyboard インターフェイス

[SecureContext, Exposed=Window]
interface Keyboard : EventTarget {
  Promise<undefined> lock(optional sequence<DOMString> keyCodes = []);
  undefined unlock();
};

navigator.keyboard.lock();

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

navigator.keyboard.lock(["Delete"]);

3. キーボードキー押下の処理

3.1. システムキー押下ハンドラー

システムキー 押下ハンドラーは、次のプロパティを持たなければならない:

• ユーザーエージェントのキーボードショートカットが処理される前に、 キー押下を処理しなければならない。

• 可能な場合は常に、システムのキーボードショートカットが処理される前に キー押下を処理するべきである。

3.1.1. 登録

システムキー押下ハンドラーを登録するには、ユーザーエージェントは、 プラットフォームが新しいキー押下の処理を開始するたびに呼び出される 低レベルフックを追加するための、プラットフォーム固有の手順に従う必要がある。

システムキー押下ハンドラーを追加する正確なプロセスは、 プラットフォームごとに異なる。一般的なプラットフォーム上でキー押下を処理する低レベルフックを 登録する方法の例については、Windows については [LowLevelKeyboardProc]、Mac OS X については [QuartzEventServices]、X Windows については [GrabKeyboard] を参照。

注記: ユーザーエージェントが別の目的でキー押下ハンドラーを すでに登録している場合、上記の要件を満たすなら、そのハンドラーを任意で拡張して Keyboard Lock 機能をサポートしてもよい。

3.1.2. 登録解除

システムキー押下ハンドラーの登録を解除するには、 ユーザーエージェントは、新しいキー押下を処理するための（以前に追加された） 低レベルフックを削除するための、プラットフォーム固有の手順に従う必要がある。

システムキー押下ハンドラーの登録と同様に、システムキー押下ハンドラーの登録解除プロセスも プラットフォーム固有である。詳細および例については、§ 3.1.1 登録に 挙げられている参考文献を参照。

3.2. キーボードイベントの処理

ユーザーがキーを押したことに応答して、システムキー押下ハンドラーが 登録されている場合、 それは次の手順を実行するべきである:

1. トップレベルブラウジングコンテキストの 現在フォーカスされている領域の フルスクリーン要素が非 null である場合、 isFullscreen を true に設定する （[Fullscreen] を参照）。

   注記: たとえば、フォーカスを持つシステムダイアログが 表示されている場合、フルスクリーン要素はフォーカスを持たない。

2. isFullscreen および キーボードロックを有効にするが すべて true に設定されている場合、次のサブ手順を実行する:

   1. keyEvent を新しいキー押下のキーイベントとする。

   2. code を、keyEvent の code 属性の値とする。

   3. 予約キーコードが空である場合、または code が 予約キーコードに列挙されている場合、 次のサブ手順を実行する:

      1. code が "Escape" と等しい場合、次の サブ手順を実行する:

         1. 任意で、ユーザーが Escape キーを長押しして フルスクリーンから抜けられることを伝えるメッセージを 画面上に重ねて表示する。

         2. キーが 2 秒間押し続けられた場合、キーボードハンドラーから抜け、 通常処理のためにそのキーをユーザーエージェントへ渡す （これによりフルスクリーン（およびアクティブであれば pointer lock）を終了する）。

      2. 通常のユーザーエージェント処理を迂回して、keyEvent を フルスクリーン文書または要素へ直接ディスパッチする。

   4. そうでない場合、そのキーイベントを、通常処理されるのと同じように処理する。 すなわち、キーイベントをディスパッチするか、通常のキーボードショートカット動作を実行する。

注記: この API は「ベストエフォート」方式で動作する。 適合する実装が、可能なすべてのキー組み合わせについて OS の既定の動作を 上書きできることは要求されない。特に、ほとんどのプラットフォームには、 アプリケーションが上書きできない “secure attention sequence”（たとえば Windows 上の Ctrl-Alt-Del）があり、この仕様はそれに優先しない。

注記: この API を実装するとき、ユーザーエージェントは、 キーボードイベントがページへディスパッチされる順序を変更しないよう注意するべきである。 予約キーコードの集合に含まれるキーは、 その集合に含まれていなかった場合に送信されていたのと同じ相対順序でディスパッチされなければならない。

4. 他の Web プラットフォーム API との統合

[Fullscreen] および [PointerLock] は、ページがユーザー体験の一部 （それぞれ画面およびマウスカーソル）を一時的に制御できるようにする API である。 これらの機能の濫用に対する懸念から、これらはユーザーがその機能を終了するために 依拠できる "escape" または "unlock" ジェスチャーを提供する。既定では、 このジェスチャーは Escape キーを押すことであり、これはこの API によって捕捉できる キーの 1 つである。

4.1. Escape キーに関する特別な考慮事項

Escape キーに関連付けられた特別な動作があるため、lock() 要求に Escape キーが含まれる場合、ユーザーエージェントは変更された挙動を考慮して、 UX に追加の変更を加える必要があるかもしれない。

たとえば、JavaScript により開始されたフルスクリーンが有効化されたときに、 ユーザーエージェントが "Press ESC to exit fullscreen" というユーザーメッセージを表示する場合、 キーボードロックが有効なときには、そのメッセージを "Press and hold ESC to exit fullscreen" と読めるよう更新する必要がある。

フルスクリーンがすでに有効になった後でキーボードロックが有効化された場合、ユーザーは フルスクリーンを終了する方法に関する複数のメッセージを見る可能性がある。 このため、開発者はフルスクリーンに入る前に lock() を呼び出すことを推奨する:

navigator.keyboard.lock();
document.documentElement.requestFullscreen();

キーボードロックとフルスクリーンを終了するときにも、複数のユーザーメッセージに関する同様の懸念があるため、 逆の順序で呼び出すことが推奨される:

document.exitFullscreen();
navigator.keyboard.unlock();

一般に、開発者は、そのキーを実際に必要とする場合にのみ、ロックされるキーの集合に Escape キーを含めるべきである。また、Escape キーがロックされる場合でも、 ユーザーが現在の状態から抜けられるようにするという主たる意味を維持することが推奨される。

4.2. フルスクリーンに関する考慮事項

現代的なユーザーエージェントでは、2 つの異なる種類のフルスクリーンを利用できる: JavaScript により開始されるフルスクリーン（[Fullscreen] API 経由）と、 ユーザーにより開始されるフルスクリーン（ユーザーがキーボードショートカットを使用して フルスクリーンに入る場合）である。ユーザーにより開始されるフルスクリーンは、 フルスクリーンモードへの出入りに使用される一般的なキーショートカットであるため、 しばしば "F11" フルスクリーンと呼ばれる。

F11 フルスクリーンと JavaScript（JS）フルスクリーンは同じようには動作しない。 ユーザーが F11 フルスクリーンに入った場合、それに入るために使用した同じ キーボードショートカットによってのみ終了できる。この場合、exitFullscreen() 関数は機能しない。さらに、JS フルスクリーンで通常発火するフルスクリーンイベントは、 F11 フルスクリーンでは送信されない。

これらの違いにより（また、F11 フルスクリーンの標準ショートカットがないため）、 Keyboard Lock API は、JavaScript により開始されたフルスクリーンがアクティブな場合にのみ有効である。 F11 フルスクリーン中は、キーボードイベントに対する Keyboard Lock 処理は行われない。

5. Pointer Lock に関する考慮事項

先に述べた UX 変更以外に、Pointer Lock の動作に変更はない。

Pointer Lock がフルスクリーンの外で有効になっている場合、Keyboard Lock は 有効にできない。

Pointer Lock、Keyboard Lock、および Fullscreen がすべて有効である場合、 Keyboard Lock に Escape キーが含まれていない限り、挙動は変更されない。その場合、 唯一の変更は UX に対するものである（上記のとおり）。

6. モバイルデバイスに関する考慮事項

これはキーボードに焦点を当てた API であり、モバイルデバイスは一般に 物理キーボードを持たないため、この API は通常、モバイルデバイス上に存在せず、 サポートされない。

ただし、物理キーボードが接続されている場合に意味があるなら、モバイルデバイスは この API をサポートすることを選択してもよい。

7. セキュリティに関する考慮事項

この API に関する 1 つの懸念は、すべてのキーを奪い取り、 （[Fullscreen] および [PointerLock] API と組み合わせて） ユーザーが Web ページから抜けることを妨げるために使用され得ることである。

これを防ぐため、ユーザーエージェントは、すべてのキーが API によって要求されている場合でも、 ユーザーがキーボードロックから抜けるための方法を提供しなければならない。

この仕様は、長い（2 秒を超える）Escape キー押下により Keyboard Lock からの終了を トリガーできるようにするサポートを要求する。さらに、ユーザーエージェントは Keyboard Lock を終了する代替手段を提供することを選択してもよい。

8. プライバシーに関する考慮事項

該当なし。この API は、現在のユーザーに関する個人情報を使用したり 明らかにしたりしない。

9. 謝辞

この提案の作成につながった議論を行った次の人々に感謝する:

Jon Dahlke (Google), Joe Downing (Google)