API виртуальной клавиатуры

API виртуальной клавиатуры предоставляет разработчикам контроль над макетом своих приложений, когда на устройствах, таких как планшеты, мобильные телефоны или других устройствах, где физическая клавиатура может отсутствовать, появляется или исчезает виртуальная клавиатура.

Веб-браузеры обычно сами обрабатывают виртуальные клавиатуры, изменяя высоту области просмотра и прокручивая до полей ввода при фокусировке.

На рисунке ниже показано различие в высоте области просмотра и позиции прокрутки на веб-странице, когда виртуальная клавиатура скрыта и когда она отображается.

Более сложные приложения или конкретные устройства, такие как мобильные телефоны с несколькими экранами, могут потребовать большего контроля над макетом при появлении виртуальной клавиатуры.

На рисунке ниже показано, что происходит на устройстве с двумя экранами, когда виртуальная клавиатура отображается только на одном из двух экранов. Область просмотра уменьшается на обоих экранах для размещения виртуальной клавиатуры, что приводит к неиспользуемому пространству на экране, где виртуальная клавиатура не отображается.

API виртуальной клавиатуры позволяет отказаться от автоматической обработки виртуальной клавиатуры браузером и взять полный контроль над ней. С помощью API виртуальной клавиатуры клавиатура по-прежнему появляется и исчезает при необходимости при фокусировке на элементах форм, но область просмотра не изменяется, и вы можете использовать JavaScript и CSS для адаптации своего макета.

API виртуальной клавиатуры состоит из трех частей:

• Интерфейс VirtualKeyboard, к которому можно получить доступ через navigator.virtualKeyboard, используется для отказа от автоматического поведения виртуальной клавиатуры, программного отображения или скрытия виртуальной клавиатуры, а также получения текущего положения и размера виртуальной клавиатуры.
• Переменные окружения CSS keyboard-inset-* предоставляют информацию о положении и размере виртуальной клавиатуры.
• Атрибут virtualkeyboardpolicy определяет, должно ли отображаться виртуальная клавиатура на элементах contenteditable.

Чтобы отказаться от автоматического поведения виртуальной клавиатуры браузера, используйте navigator.virtualKeyboard.overlaysContent = true. Браузер больше не будет автоматически изменять размер области просмотра для выделения места под виртуальную клавиатуру, которая вместо этого будет накладываться поверх вашего контента.

После отказа от стандартного поведения браузера вы можете получить текущую геометрию виртуальной клавиатуры, используя navigator.virtualKeyboard.boundingRect, и соответствующим образом адаптировать макет с помощью CSS и JavaScript. Кроме того, вы можете прослушивать изменения геометрии, такие как отображение или скрытие клавиатуры, с помощью события geometrychange.

Это полезно для позиционирования важных элементов пользовательского интерфейса в области, не покрытой виртуальной клавиатурой.

В приведенном ниже фрагменте кода событие geometrychange используется для определения изменения геометрии виртуальной клавиатуры; затем он получает доступ к свойству boundingRect для запроса размера и положения виртуальной клавиатуры:

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

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

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 получает высоту виртуальной клавиатуры.

<style>
  body {
    display: grid;
    margin: 0;
    height: 100vh;
    grid-template:
      "messages" 1fr
      "input" auto
      "keyboard" env(keyboard-inset-height, 0px);
  }
</style>
<ul id="messages"></ul>
<input type="text" />
<script>
  if ("virtualKeyboard" in navigator) {
    navigator.virtualKeyboard.overlaysContent = true;
  }
</script>

По умолчанию элементы, использующие атрибут contenteditable, также вызывают виртуальную клавиатуру при нажатии или щелчке. В определенных ситуациях может потребоваться предотвратить это поведение и вместо этого отобразить виртуальную клавиатуру после другого события.

Установите атрибут virtualkeyboardpolicy в значение manual для предотвращения стандартной обработки виртуальной клавиатуры в браузере и для обработки её самостоятельно, используя интерфейс VirtualKeyboard и методы show() и hide().

В приведенном ниже фрагменте кода показано, как использовать атрибут virtualkeyboardpolicy и метод navigator.virtualKeyboard.show() для отображения виртуальной клавиатуры при двойном щелчке:

<div contenteditable virtualkeyboardpolicy="manual" id="editor"></div>
<script>
  if ("virtualKeyboard" in navigator) {
    navigator.virtualKeyboard.overlaysContent = true;

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

VirtualKeyboard Экспериментальная

Предоставляет функции, которые извлекают карты макета клавиатуры и переключают захват нажатий клавиш с физической клавиатуры.

Navigator.virtualKeyboard Только для чтения Экспериментальная

Возвращает ссылку на API VirtualKeyboard для взятия под контроль виртуальной клавиатуры.

HTMLElement.virtualkeyboardpolicy Экспериментальная

Строка, указывающая, следует ли использовать стандартную политику браузера для отображения виртуальной клавиатуры при фокусировке на элементе или обрабатывать отображение виртуальной клавиатуры вручную.

• Полный контроль с помощью API VirtualKeyboard