VirtualKeyboard API

实验性： 这是一个实验性技术
在生产环境中使用此功能前，请仔细查看浏览器兼容性表格。

安全上下文： 此功能仅在安全上下文（HTTPS）中，某些或所有支持的浏览器中可用。

VirtualKeyboard API 为开发者提供了在平板电脑、手机或其他可能没有硬件键盘的设备上，当屏幕虚拟键盘出现和消失时控制应用程序布局的能力。

Web 浏览器通常会自行处理虚拟键盘，通过调整视口高度并在聚焦输入字段时滚动。

下图说明了当设备的屏幕虚拟键盘隐藏和显示时，网页的视口高度和滚动位置的差异。

Two devices, one without a virtual keyboard, showing that the webpage can use most of the device's vertical space, and one with a virtual keyboard, showing that the webpage can only be displayed in the remaining space

更复杂的应用程序或特定的设备（例如多屏幕手机）可能需要在虚拟键盘出现时对其布局进行更多控制。

下图显示了在双屏设备上，当虚拟键盘仅出现在两个屏幕中的一个屏幕上时会发生的情况。为了适应虚拟键盘，两个屏幕的视口都会变小，导致在未显示虚拟键盘的屏幕上出现浪费的空间。

A dual-screen device, with its virtual keyboard displayed on one screen, showing that the webpage can only use the vertical space that remains after the keyboard was displayed, even if that leaves empty space on the other screen

VirtualKeyboard API 可用于选择退出浏览器自动处理虚拟键盘的方式，而是完全控制它。使用 VirtualKeyboard API，键盘仍然会在需要时在表单控件聚焦时出现和消失，但视口不会改变，您可以使用 JavaScript 和 CSS 调整布局。

概念

VirtualKeyboard API 由三个部分组成

通过 navigator.virtualKeyboard 访问的 VirtualKeyboard 接口用于选择退出自动虚拟键盘行为，以编程方式显示或隐藏虚拟键盘，以及获取虚拟键盘的当前位置和大小。
keyboard-inset-* CSS 环境变量提供有关虚拟键盘位置和大小的信息。
virtualkeyboardpolicy 属性指定虚拟键盘是否应在 contenteditable 元素上显示。

选择退出自动虚拟键盘行为

要选择退出浏览器的自动虚拟键盘行为，请使用 navigator.virtualKeyboard.overlaysContent = true。浏览器将不再自动调整视口大小以腾出空间用于虚拟键盘，而是会将虚拟键盘覆盖在您的内容之上。

使用 JavaScript 检测虚拟键盘几何形状

选择退出默认浏览器行为后，您可以使用 navigator.virtualKeyboard.boundingRect 获取虚拟键盘的当前几何形状，并使用 CSS 和 JavaScript 适当地调整布局。此外，您可以通过使用 geometrychange 事件来监听几何形状的变化，例如当键盘显示或隐藏时。

这对于将重要的 UI 元素定位在未被虚拟键盘覆盖的区域很有用。

下面的代码片段使用 geometrychange 事件来检测虚拟键盘几何形状何时发生变化；然后它访问 boundingRect 属性来查询虚拟键盘的大小和位置

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

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

使用 CSS 环境变量检测虚拟键盘几何形状

VirtualKeyboard API 还公开了以下 CSS 环境变量：keyboard-inset-top、keyboard-inset-right、keyboard-inset-bottom、keyboard-inset-left、keyboard-inset-width 和 keyboard-inset-height。

keyboard-inset-* CSS 环境变量可用于使用 CSS 调整布局以适应虚拟键盘的外观。它们通过从视口边缘的顶部、右侧、底部和左侧内边距来定义一个矩形。如果需要，还可以使用 width 和 height 变量。

下面的代码片段使用 keyboard-inset-height CSS 变量为虚拟键盘保留空间，使其出现在类似聊天的应用程序中消息列表和输入字段下方。当虚拟键盘隐藏时，env() 函数返回 0px，并且 keyboard 网格区域隐藏。消息和输入元素可以占据视口的全部高度。当虚拟键盘出现时，keyboard 网格区域将获取虚拟键盘的高度。

html

<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` 元素上的虚拟键盘

默认情况下，使用 contenteditable 属性的元素在被点击或轻触时也会触发虚拟键盘。在某些情况下，可能需要阻止此行为，而是在不同的事件后显示虚拟键盘。

将 virtualkeyboardpolicy 属性设置为 manual 以阻止浏览器默认处理虚拟键盘，而是通过使用 VirtualKeyboard 接口的 show() 和 hide() 方法自行处理。

下面的代码片段显示了如何使用 virtualkeyboardpolicy 属性和 navigator.virtualKeyboard.show() 方法改为在双击时显示虚拟键盘

html

<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 只读实验性: 返回对 VirtualKeyboard API 的引用，以控制屏幕上的虚拟键盘。
HTMLElement.virtualkeyboardpolicy 实验性: 一个字符串，指示是在元素聚焦时使用浏览器的默认策略显示虚拟键盘，还是手动处理虚拟键盘的显示。

规范

规范
VirtualKeyboard API # the-virtualkeyboard-interface

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅

使用 VirtualKeyboard API 实现完全控制