此页面由 Cloud Translation API 翻译。

使用 VirtualKeyboard API 进行完全控制

Thomas Steiner

浏览器支持

<ph type="x-smartling-placeholder">
<ph type="x-smartling-placeholder">
<ph type="x-smartling-placeholder">
<ph type="x-smartling-placeholder">

平板电脑或手机等设备通常都有用于输入文字的虚拟键盘。与始终存在且始终相同的物理键盘不同，虚拟键盘会出现和消失，具体取决于用户的操作，它也可以动态适应基础模型， inputmode 属性。

这种灵活性的代价是浏览器布局引擎必须获知并可能需要将文档布局调整为获得补偿。例如，用户要输入的输入字段可能会被虚拟键盘，因此浏览器必须将其滚动到用户视野范围内。

传统上，浏览器已独自应对这一挑战，但应用的情况更为复杂可能需要更好地控制浏览器的行为。例如，跨屏移动设备传统方法会导致“浪费”屏幕空间（如果虚拟键盘）仅在一个屏幕段上显示，但可用的视口在两个屏幕上会缩小。下图显示了如何使用 VirtualKeyboard API 优化布局以弥补虚拟键盘的存在。

传统方法

对于这种情况，Virtual 键盘 API 大显身手。它包含三个部分：

navigator 对象的 VirtualKeyboard 接口，用于以编程方式访问虚拟从 JavaScript 键盘切换。
一组 CSS 环境变量，用于提供有关虚拟键盘的外观。
虚拟键盘政策，用于确定是否应显示虚拟键盘。

当前状态

在桌面设备和移动设备上，Chromium 94 均提供了 Virtual 键盘 API。

功能检测和浏览器支持

如需检测当前浏览器是否支持 Virtualkeyboard API，请使用以下代码段：

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

使用 Virtualkeyboard API

Virtual 键盘 API 向 navigator 对象添加了一个新的接口 VirtualKeyboard。

启用新的虚拟键盘行为

要告知浏览器您会自行处理虚拟键盘遮挡，您需要执行以下操作：首先，通过设置布尔值属性 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 环境变量

Virtual 键盘 API 公开了一组 CSS 环境变量，这些变量提供虚拟键盘的外观。它们的建模方式与 inset CSS 属性类似，即与顶部、右侧、底部和/或左侧属性相对应。

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>

演示

您可以在演示（关于 Glitch）。请务必浏览源代码，了解其实现方式。虽然可以在 iframe 嵌入中观察 geometrychange 事件，但实际的虚拟键盘行为需要在单独的浏览器标签页中打开演示版。

实用链接

致谢

Virtual 键盘 API 由 Microsoft 的 Anupam Snigdha 指定，其贡献由曾是 Microsoft 的编辑 Grisha Lyukshin。主打图片提供方 @freestocks 不启动。