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

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

Thomas Steiner

対応ブラウザ

タブレットやスマートフォンなどのデバイスには、通常、テキスト入力用の仮想キーボードが搭載されています。常に存在し、常に同じ状態の物理キーボードとは異なり、仮想キーボードはユーザーの操作に応じて表示と非表示を切り替えます。また、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 を追加します。

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

仮想キーボードのオクルージョンを自分で処理することをブラウザに伝えるには、まず、ブール値プロパティ 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 プロパティには virtualKeyboard オブジェクトが含まれます。このオブジェクトには、上記で説明したように、DOMRect として仮想キーボードの新しいインセットジオメトリが含まれています。

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 環境変数を公開します。これらは、CSS プロパティ inset と同様にモデル化されています。つまり、top、right、bottom、left プロパティに対応しています。

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 が仕様を定義し、同じく Microsoft の元エディタである Grisha Lyukshin が貢献しました。

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