このページは Cloud Translation API によって翻訳されました。

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

Thomas Steiner

Twitter GitHub Glitch Mastodon ホームページ

対応ブラウザ

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

この柔軟性のためには、ブラウザのレイアウトエンジンに仮想キーボードの有無を通知する必要があり、補正するためにドキュメントのレイアウトを調整することが必要になる可能性があります。たとえば、ユーザーが入力しようとしている入力フィールドが仮想キーボードによってわかりにくくなっている場合、ブラウザはそのフィールドをスクロールする必要があります。

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

従来のアプローチでは、

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

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

現在のステータス

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

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

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

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

VirtualKeyboard API の使用

VirtualKeyboard API により、新しいインターフェース VirtualKeyboard が navigator オブジェクトに追加されます。

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

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

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 プロパティと同様にモデル化され、上、右、下、左のプロパティに対応します。

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 は、キーワードが auto と manual という文字列の属性です。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 が指定し、元編集者の Grisha Lyukshin も Microsoft からも貢献しました。@freestocks 提供の Unsplash のヒーロー画像

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