Эта страница переведена с помощью Cloud Translation API.

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

Thomas Steiner

Browser Support

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

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

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

Традиционный подход приводит к

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

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

Текущий статус

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

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

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

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

Использование API VirtualKeyboard

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 . Вставка соответствует свойствам 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

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

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

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

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