VirtualKeyboard API

このセクションは規範的ではありません。

バーチャルキーボード（VK）は、ハードウェアキーボードが利用できない状況で入力のために使用される画面上のキーボードです。 ユーザーエージェントは、以下の方法でVKの存在に対応しますが、この情報はウェブ開発者には公開されません： 1. ユーザーエージェントをVKの上に再配置する 2. VKがレイアウトビューポートを覆わないようにレイアウトビューポートのサイズを縮小する 3. ビジュアルビューポートのサイズを縮小し、レイアウトビューポートにパディングを追加してVKの上に移動できるようにする このAPIは、ユーザーエージェントがレイアウトおよびビジュアルビューポートを変更せず、 代わりにVKとレイアウトビューポートの交差情報を提供するという第4の選択肢を提供します。 これにより、著者はJavaScriptやCSS環境変数を使ってウェブページのレイアウトを適応させることができます。

デュアルスクリーンデバイス上のバーチャルキーボードの図

シングルタッチスクリーンデバイス上のバーチャルキーボードの図

非規範的と記載されているセクションだけでなく、この仕様書のすべての作成ガイドライン、図、例、および注記は非規範的です。それ以外の内容はすべて規範的です。

この文書におけるキーワード MUST および MUST NOT は、 BCP 14 [RFC2119] [RFC8174] に記載されている通り、すべて大文字で表記されている場合のみ、その意味として解釈してください。

この仕様は、1つの製品に適用される適合基準を定義しています。それは、この仕様に含まれるインターフェイスを実装する ユーザーエージェントです。

アルゴリズムや特定の手順として記載された適合要件は、最終的な結果が同等である限り、どのような方法で実装しても構いません。 （特に、この仕様で定義されているアルゴリズムは、分かりやすさを重視しており、高速であることを意図していません。）

WebIDLpartial interface Navigator {
    [SecureContext, SameObject] readonly attribute VirtualKeyboard virtualKeyboard;
};

[Exposed=Window, SecureContext]
interface VirtualKeyboard : EventTarget {
    undefined show();
    undefined hide();
    readonly attribute DOMRect boundingRect;
    attribute boolean overlaysContent;
    attribute EventHandler ongeometrychange;
};

VirtualKeyboard オブジェクトには、以下が関連付けられています：

DOMRect。初期値は全て 0 です。

boolean型で、初期値は false です。この属性が true に設定されている場合、ユーザーエージェントは MUST NOT 自身の document の viewport または visual viewport をリサイズしてはなりません。

show() メソッド

このメソッドは以下の手順に従うものとします：

1. window を this の 関連グローバルオブジェクト とします。window が Window オブジェクトであることを確認します。
2. window が sticky activation を持たない場合は、この手順を中止します。
3. フォーカスされている要素がフォームコントロール（例えば textarea 要素の値など）でない場合や、編集ホスト （例：contenteditable を使用） でない場合、この手順を中止します。
4. virtualKeyboardPolicy が manual でない場合、または inputMode 属性値が none の場合、この手順を中止します。
5. システムAPIを呼び出してVKを表示します。
6. 並行して、以下の手順を実行します：
   1. システムによってバーチャルキーボードが表示されるのを待ちます。
   2. set the virtual keyboard bounding rect をキーボードのOSから報告されたバウンディング矩形と document の viewport 矩形を使って呼び出します。
   3. "geometrychange" イベントを this に発火します。

hide() メソッド

このメソッドは以下の手順に従うものとします：

1. window を this の 関連グローバルオブジェクト とします。window が Window オブジェクトであることを確認します。
2. window が sticky activation を持たない場合は、この手順を中止します。
3. フォーカスされている要素の virtualKeyboardPolicy が manual でない場合、または inputMode 属性値が none の場合、この手順を中止します。
4. システムAPIを呼び出してVKを非表示にします。
5. 並行して、以下の手順を実行します：
   1. システムによってバーチャルキーボードが非表示になるのを待ちます。
   2. set the virtual keyboard bounding rect をキーボードのOSから報告されたバウンディング矩形（すべて 0 の値）と document の viewport 矩形を使って呼び出します。
   3. "geometrychange" イベントを this に発火します。

注記

プラットフォームのヒューリスティクスによって、VKの show() および hide() に追加の制限が課される場合があります。例：Windowsではポインタタイプがタッチまたはペンである必要があります。

注記

懸念を示す人もいます show() および hide() メソッドが promise ベースでないことに対してですが、VKの表示状態が変化した際に ongeometrychange イベントが発火するため、戻り値は不要であり、ウェブ開発者にとってはこの設計の方が望ましいと考えています。

overlaysContent

overlaysContent の getter 手順は、this の overlaysContent を返します。

overlaysContent の setter 手順は、this の overlaysContent に与えられた値を設定します。

boundingRect

この属性は、VKと document の viewport との交差領域をクライアント座標系で報告します。set the virtual keyboard bounding rect を呼び出してください。

set the virtual keyboard bounding rect

set the virtual keyboard bounding rect を、osk（オンスクリーンキーボードの矩形を表すDOMRect）と lv（document の viewport 矩形を表すDOMRect）を入力として実行するには、次の手順を実行します：

1. osk を show() または hide() を this で実行した結果のオンスクリーンキーボードの矩形とします。
2. lv を document の viewport で、show() または hide() を this で実行した結果とします。
3. osk を lv の座標空間にマッピングします。
4. bounds を DOMRect オブジェクトとします。
5. bounds を lv と osk の交差領域で更新します。
6. bounds を lv の座標空間にマッピングします。
7. bounds を返します。

boundingRect の getter 手順は、this の boundingRect を返します。

ongeometrychange

このイベントは、VKと document の viewport の交差領域が変更されたとき（例：VKが表示・非表示になった時やブラウザーウィンドウが再配置された時など）に発火されます。

WebIDL partial interface mixin ElementContentEditable {
     [CEReactions] attribute DOMString virtualKeyboardPolicy;
};

virtualKeyboardPolicy は、列挙属性であり、キーワードは 空文字列、auto、manual です。IDL属性は、同名のコンテンツ属性を反映する必要があります。 この属性が contenteditable ホストの要素に指定されている場合、auto は対応する編集可能要素がフォーカスまたはタップされたときに自動的にVKを表示し、manual は編集可能要素のフォーカスやタップによるVKの状態変化を切り離し、VKはそのままになります。
virtualKeyboardPolicy 属性値の設定変更は、現在定義されている動作を打ち消します。ただし、auto から 空文字列 またはその逆への変更は除きます。

• auto 列挙属性が設定されている場合、VKはブラウザーによって処理されます。
• manual 列挙属性が設定されている場合、VKのデフォルト処理をブラウザーで行わず、スクリプトでハンドルする必要があります。
• 空文字列 列挙属性が設定されている場合、VKはブラウザーによって処理されます。

VirtualKeyboard API は、ウェブ開発者がバーチャルキーボードのサイズを計算し、レイアウトを宣言的に調整できるように 6 つの新しい CSS 環境変数 を提案しています。