VirtualKeyboard API によるフル コントロール

対応ブラウザ

  • Chrome: 94。
  • Edge: 94。
  • Firefox: サポートされていません。
  • Safari: サポートされていません。

ソース

タブレットやスマートフォンなどのデバイスには、通常、テキスト入力用の仮想キーボードが搭載されています。常に存在し、常に同じ物理キーボードとは異なり、仮想キーボードは、ユーザーの操作に応じて表示 / 非表示を切り替えることができます。また、inputmode 属性などに基づいて動的に適応させることもできます。

この柔軟性には、ブラウザのレイアウト エンジンに仮想キーボードの存在を通知する必要があり、補正するためにドキュメントのレイアウトを調整する必要があるという代償があります。たとえば、ユーザーが入力しようとしている入力フィールドが仮想キーボードで隠れている場合、ブラウザはそれをスクロールして表示する必要があります。

従来、ブラウザは独自にこの課題に対処してきましたが、より複雑なアプリケーションでは、ブラウザの動作をより細かく制御することが必要になる場合があります。たとえば、マルチスクリーン モバイル デバイスでは、従来のアプローチでは仮想キーボードが 1 つの画面セグメントにのみ表示されるため、画面領域が「無駄」になりますが、それでも両方の画面で使用可能なビューポートが縮小されます。次の図は、VirtualKeyboard API を使用してドキュメントのレイアウトを動的に最適化し、仮想キーボードの存在を補正する方法を示しています。

従来のアプローチでは、

このような状況で役立つのが VirtualKeyboard API です。これは次の 3 つの部分で構成されます。

  • JavaScript から仮想キーボードにプログラムでアクセスするための navigator オブジェクトの VirtualKeyboard インターフェース。
  • 仮想キーボードの外観に関する情報を提供する一連の CSS 環境変数。
  • 仮想キーボードを表示するかどうかを決定する仮想キーボード ポリシー。

現在のステータス

VirtualKeyboard API は、パソコンとモバイルの Chromium 94 から利用できます。

機能の検出とブラウザのサポート

VirtualKeyboard API が現在のブラウザでサポートされているかどうかを検出するには、次のスニペットを使用します。

if ('virtualKeyboard' in navigator) {
 
// The VirtualKeyboard API is supported!
}

VirtualKeyboard API を使用する

VirtualKeyboard API は、navigator オブジェクトに新しいインターフェース VirtualKeyboard を追加します。

新しい仮想キーボードの動作を有効にする

仮想キーボードのオクルージョンを自分で処理することをブラウザに伝えるには、まず、ブール値プロパティ overlaysContenttrue に設定して、新しい仮想キーボードの動作を有効にする必要があります。

navigator.virtualKeyboard.overlaysContent = true;

仮想キーボードの表示と非表示

仮想キーボードをプログラムで表示するには、show() メソッドを呼び出します。これが機能するには、フォーカスされている要素がフォーム コントロール(textarea 要素など)であるか、編集ホストである必要があります(contenteditable 属性を使用するなど)。このメソッドは常に undefined を返しますが、仮想キーボードが表示されなかった場合は geometrychange イベントをトリガーします。

navigator.virtualKeyboard.show();

仮想キーボードを非表示にするには、hide() メソッドを呼び出します。このメソッドは常に undefined を返しますが、仮想キーボードが以前に表示されていた場合は geometrychange イベントをトリガーします。

navigator.virtualKeyboard.hide();

現在のジオメトリを取得する

boundingRect プロパティを調べると、バーチャル キーボードの現在のジオメトリを取得できます。仮想キーボードの現在のサイズを DOMRect オブジェクトとして公開します。インセットは、top、right、bottom、left プロパティに対応します。

const { x, y, width, height } = navigator.virtualKeyboard.boundingRect;
console
.log('Virtual keyboard geometry:', x, y, width, height);

ジオメトリの変更に関する通知

仮想キーボードが表示されたり消えたりすると、geometrychange イベントが送信されます。このイベントの target プロパティには、前述のとおり、DOMRect として仮想キーボード インセットの新しいジオメトリを含む virtualKeyboard オブジェクトが含まれます。

navigator.virtualKeyboard.addEventListener('geometrychange', (event) => {
 
const { x, y, width, height } = event.target.boundingRect;
  console
.log('Virtual keyboard geometry changed:', x, y, width, height);
});

CSS 環境変数

VirtualKeyboard API は、仮想キーボードの外観に関する情報を提供する一連の CSS 環境変数を公開します。これらは inset CSS プロパティと同様にモデル化されます。つまり、top、right、Bottom、左のプロパティに対応します。

  • keyboard-inset-top
  • keyboard-inset-right
  • keyboard-inset-bottom
  • keyboard-inset-left
  • keyboard-inset-width
  • keyboard-inset-height

仮想キーボード インセットは 6 つの環境変数で、ビューポートの端からの上下左右のインセットによって長方形を定義します。幅と高さのインセットは、デベロッパーの作業効率を考慮して、他のインセットから計算されます。フォールバック値が指定されていない場合、各キーボード インセットのデフォルト値は 0px です。

通常、環境変数は次の例のように使用します。

.some-class {
 
/**
   * Use a margin that corresponds to the virtual keyboard's height
   * if the virtual keyboard is shown, else use the fallback value of `50px`.
   */

 
margin-block-end: env(keyboard-inset-height, 50px);
}

.some-other-class {
 
/**
   * Use a margin that corresponds to the virtual keyboard's height
   * if the virtual keyboard is shown, else use the default fallback value of `0px`.
   */

 
margin-block-end: env(keyboard-inset-height);
}

仮想キーボードのポリシー

編集可能な要素がフォーカスされているときに、仮想キーボードが表示されないことがあります。たとえば、ユーザーがセルをタップしてその値を別のセルの数式に含めることができるスプレッドシート アプリケーションがあります。virtualkeyboardpolicy は、キーワードが文字列 automanual の属性です。contenteditable ホストである要素に指定すると、auto により、対応する編集可能な要素がフォーカスまたはタップされたときに、仮想キーボードが自動的に表示されます。manual は、編集可能な要素のフォーカスとタップと、仮想キーボードの現在の状態の変更を切り離します。

<!-- Do nothing on regular focus, but show the virtual keyboard on double-click. -->
<div
 
contenteditable
 
virtualkeyboardpolicy="manual"
 
inputmode="text"
 
ondblclick="navigator.virtualKeyboard.show();"
>
  Double-click to edit.
</div>

デモ

VirtualKeyboard API の動作は、Glitch のデモで確認できます。ソースコードを参照して、実装方法を確認してください。geometrychange イベントは iframe 埋め込みで確認できますが、実際の仮想キーボードの動作を確認するには、独自のブラウザタブでデモを開く必要があります。

謝辞

VirtualKeyboard API は、Microsoft の Anupam Snigdha が仕様を定義し、同じく Microsoft の元エディタである Grisha Lyukshin が貢献しました。