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

Thomas Steiner

Поддержка браузера

• 94
• 94
• Икс
• Икс

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

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

Традиционно браузеры справлялись с этой проблемой самостоятельно, но более сложные приложения могут требовать большего контроля над поведением браузера. Примеры включают многоэкранные мобильные устройства, где традиционный подход приведет к «растраченной» экранной площади, если виртуальная клавиатура отображается только на одном сегменте экрана, но, тем не менее, доступное окно просмотра сокращается на обоих экранах. На изображении ниже показано, как можно использовать API VirtualKeyboard для динамической оптимизации макета документа, чтобы компенсировать присутствие виртуальной клавиатуры.

В подобных ситуациях на помощь приходит API VirtualKeyboard. Он состоит из трех частей:

• Интерфейс VirtualKeyboard объекта navigator для программного доступа к виртуальной клавиатуре из JavaScript.
• Набор переменных среды CSS, которые предоставляют информацию о внешнем виде виртуальной клавиатуры.
• Политика виртуальной клавиатуры, определяющая, следует ли отображать виртуальную клавиатуру.

Текущее состояние

API VirtualKeyboard доступен в Chromium 94 на настольных компьютерах и мобильных устройствах.

Обнаружение функций и поддержка браузера

Чтобы определить, поддерживается ли API VirtualKeyboard в текущем браузере, используйте следующий фрагмент:

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

Использование API виртуальной клавиатуры

API VirtualKeyboard добавляет новый интерфейс VirtualKeyboard к объекту navigator .

Согласие на новое поведение виртуальной клавиатуры

Чтобы сообщить браузеру, что вы самостоятельно заботитесь о перекрытиях виртуальной клавиатуры, вам необходимо сначала согласиться на новое поведение виртуальной клавиатуры, установив для логического свойства overlaysContent значение true .

navigator.virtualKeyboard.overlaysContent = true;

Отображение и скрытие виртуальной клавиатуры

Вы можете программно отобразить виртуальную клавиатуру, вызвав ее метод show() . Чтобы это работало, элемент в фокусе должен быть элементом управления формой (например, элементом textarea ) или хостом редактирования (например, с помощью атрибута contenteditable ). Метод всегда возвращает undefined , но вызывает событие geometrychange , если виртуальная клавиатура ранее не отображалась.

navigator.virtualKeyboard.show();

Чтобы скрыть виртуальную клавиатуру, вызовите метод hide() . Метод всегда возвращает undefined , но вызывает событие geometrychange , если ранее отображалась виртуальная клавиатура.

navigator.virtualKeyboard.hide();

Получение текущей геометрии

Вы можете получить текущую геометрию виртуальной клавиатуры, просмотрев boundingRect . Он отображает текущие размеры виртуальной клавиатуры как объект DOMRect . Вставка соответствует верхним, правым, нижним и/или левым свойствам.

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

API VirtualKeyboard предоставляет набор переменных среды CSS, которые предоставляют информацию о внешнем виде виртуальной клавиатуры. Они моделируются аналогично свойству CSS- inset , то есть соответствуют свойствам top, right, low и/или left.

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

Вставки виртуальной клавиатуры — это шесть переменных среды, которые определяют прямоугольник по его верхним, правым, нижним и левым вставкам от края области просмотра. Вставки по ширине и высоте рассчитываются на основе других вставок для эргономики разработчика. Значение по умолчанию для каждой вставки клавиатуры — 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>

Демо

Вы можете увидеть API VirtualKeyboard в действии в демо-версии на Glitch. Обязательно изучите исходный код , чтобы увидеть, как он реализован. Хотя события geometrychange можно наблюдать во вставке iframe, фактическое поведение виртуальной клавиатуры требует открытия демо-версии в отдельной вкладке браузера .

Полезные ссылки

• Спецификация
• Репозиторий
• Запись ChromeStatus
• Ошибка хрома
• Обзор тегов W3C
• Запрос позиции по стандартам Mozilla
• Запрос позиции по стандартам WebKit

Благодарности

API VirtualKeyboard был разработан Анупамом Снигдой из Microsoft при участии бывшего редактора Гриши Люкшина, также из Microsoft. Главное изображение от @freestocks на Unsplash .