Эта страница переведена с помощью 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 . Отступ соответствует свойствам «верх», «правый», «нижний» и/или «левый».

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 , то есть соответствуют свойствам «верх», «правый», «нижний» и/или «левый».

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 . Если атрибут auto указан для элемента, являющегося хостом contenteditable , то он автоматически отображает виртуальную клавиатуру при фокусе или касании редактируемого элемента, а 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 в демо-версии . Обязательно изучите исходный код , чтобы понять, как он реализован. Хотя события geometrychange можно наблюдать во встроенном iframe, для реального поведения виртуальной клавиатуры требуется открыть демо-версию в отдельной вкладке браузера .

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

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

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

Полный контроль с помощью API VirtualKeyboard. Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.