仮想キーボード API

概要

VirtualKeyboard API は、以下の 3 つの部分で構成されています。

• VirtualKeyboard インターフェイス。これは navigator.virtualKeyboard からアクセスでき、仮想キーボードの自動表示機能を無効にしたり、プログラムから仮想キーボードを表示・非表示にしたり、仮想キーボードの現在の位置やサイズを取得したりするために使用します。
• CSS の keyboard-inset-* 環境変数は、仮想キーボードの位置やサイズに関する情報を提供します。
• virtualkeyboardpolicy 属性は、contenteditable 要素に仮想キーボードが現れるかどうかを指定します。

仮想キーボードの自動動作を無効にする

ブラウザーの仮想キーボードの自動動作を無効にするには、navigator.virtualKeyboard.overlaysContent = true を使用してください。これにより、ブラウザーは仮想キーボードを表示するための空間を確保するためにビューポートのサイズを自動的に変更できなくなり、代わりに仮想キーボードがコンテンツの上に重ねて表示されるようになります。

JavaScript で仮想キーボードの形状を検出する

ブラウザーのデフォルトの動作を無効にしたら、navigator.virtualKeyboard.boundingRect を使用して仮想キーボードの現在の形状を取得し、CSS や JavaScript を使ってレイアウトを適宜調整することができます。さらに、geometrychange イベントを使用することで、キーボードの表示・非表示など、形状の変更を監視することも可能です。

これは、重要な UI の要素を、仮想キーボードで網羅されていない領域に配置するのに有益です。

次のコードスニペットでは、geometrychange イベントを使用して、仮想キーボードの形状が変更されたことを検知しています。その後、boundingRect プロパティにアクセスして、仮想キーボードのサイズと位置を取得しています。

if ("virtualKeyboard" in navigator) {
  navigator.virtualKeyboard.overlaysContent = true;

  navigator.virtualKeyboard.addEventListener("geometrychange", (event) => {
    const { x, y, width, height } = event.target.boundingRect;
  });
}

CSS 環境変数を使用して仮想キーボードの形状を検出する

仮想キーボード API では、CSS 環境変数として keyboard-inset-top、keyboard-inset-right、keyboard-inset-bottom、keyboard-inset-left、keyboard-inset-width、keyboard-inset-height も公開しています。

CSS の keyboard-inset-* 環境変数は、CSS を使用してレイアウトを仮想キーボードの外観に合わせて調整するのに有益です。これらは、ビューポートの端からの上、右、下、左のインセットによって矩形を定義します。必要に応じて、width および height 変数も利用できます。

以下のコードスニペットでは、CSS 環境変数 keyboard-inset-height を使用して、チャット風アプリケーションにおいて、メッセージ一覧や入力フィールドの下に仮想キーボードが現れるための空間を確保しています。仮想キーボードが非表示のとき、env() 関数は 0px を返し、keyboard グリッド領域は非表示になります。メッセージや入力要素は、ビューポートの高さ全体を占めることができます。仮想キーボードが現れると、keyboard グリッド領域の高さは仮想キーボードの高さになります。

<ul id="messages"></ul>
<input type="text" />

body {
  display: grid;
  margin: 0;
  height: 100vh;
  grid-template:
    "messages" 1fr
    "input" auto
    "keyboard" env(keyboard-inset-height, 0px);
}

if ("virtualKeyboard" in navigator) {
  navigator.virtualKeyboard.overlaysContent = true;
}

contenteditable の要素上の仮想キーボードを制御する

デフォルトで、contenteditable 属性を使用している要素は、タップまたはクリックされると同時に仮想キーボードも起動します。状況によっては、この動作を無効にし、別のイベントが発生した後に仮想キーボードを表示させたい場合もあるでしょう。

virtualkeyboardpolicy 属性を manual に設定すると、ブラウザーによる仮想キーボードのデフォルトの処理が抑制され、代わりに VirtualKeyboard インターフェイスの show() および hide() メソッドを使用して、自分で処理することができます。

下記のコードスニペットは、virtualkeyboardpolicy 属性と navigator.virtualKeyboard.show() メソッドを使用して、ダブルクリック時に仮想キーボードを表示させる方法を示しています。

<div contenteditable virtualkeyboardpolicy="manual" id="editor"></div>

if ("virtualKeyboard" in navigator) {
  navigator.virtualKeyboard.overlaysContent = true;

  const editor = document.getElementById("editor");
  editor.addEventListener("dblclick", () => {
    navigator.virtualKeyboard.show();
  });
}

インターフェイス

VirtualKeyboard

キーボードレイアウトマップを取得したり、物理キーボードからのキー入力の捕捉をオン／オフに切り替えたりする機能を提供します。

他のインターフェイスへの拡張

Navigator.virtualKeyboard 読取専用

画面上の仮想キーボードを制御するための VirtualKeyboard API への参照を返します。

HTMLElement.virtualkeyboardpolicy

要素にフォーカスが当たった際に、仮想キーボードの表示についてブラウザーのデフォルトのポリシーを使用するか、それとも手動で処理するかを示す文字列。

仕様書

ブラウザーの互換性

関連情報

• Full control with the VirtualKeyboard API