虚拟键盘 API

本节是非规范性的。

虚拟键盘 (VK) 是用于输入的屏幕键盘，适用于没有硬件键盘的场景。用户代理在以下情况下响应 VK 的存在，但不会将此信息暴露给 Web 开发者： 1. 将用户代理重新定位到 VK 之上 2. 减小布局视口的大小，以确保 VK 不会遮挡它 3. 减小视觉视口的大小，并为布局视口增加内边距，以确保它可以移动到 VK 之上 该 API 提供了第四个选项，允许用户代理保持其布局和视觉视口不变，而是提供 VK 和布局视口的交集信息，以便作者可以使用 JavaScript 或 CSS 环境变量调整其网页的布局。

显示双屏设备上虚拟键盘的图像

显示单触摸屏设备上虚拟键盘的图像

除了标记为非规范性的部分外，本规范中的所有创作指南、图表、示例和注释均为非规范性的。本规范中的其他所有内容均为规范性的。

本文档中的关键字 必须 和 不得 应按照 BCP 14 [RFC2119] [RFC8174] 的描述进行解释，且仅在这些词汇以全大写形式出现时如此解释。

本规范定义的合规性标准适用于单一产品：实现了其包含的接口的用户代理。

以算法或特定步骤表述的合规性要求可以以任何方式实现，只要最终结果是等效的即可。（特别是，本规范中定义的算法旨在易于理解，而非为了高效运行。）

WebIDLpartial interface Navigator {
        [SecureContext, SameObject] readonly attribute VirtualKeyboard virtualKeyboard;
    };
    
    [Exposed=Window, SecureContext]
    interface VirtualKeyboard : EventTarget {
        undefined show();
        undefined hide();
        readonly attribute DOMRect boundingRect;
        attribute boolean overlaysContent;
        attribute EventHandler ongeometrychange;
    };

VirtualKeyboard 对象有以下关联属性：

DOMRect，初始值为零。

一个布尔值，初始值为 false。当该属性设置为 true 时，用户代理不得调整其文档的视口或视觉视口的大小。

show() 方法

该方法必须按照以下步骤执行：

1. 令 window 为 this 的 相关全局对象。断言 window 是 Window 对象。
2. 如果 window 没有 粘性激活，则中止这些步骤。
3. 如果焦点元素不是表单控件（例如 textarea 元素的值）或 编辑主机（例如使用 contenteditable） ，则中止这些步骤。
4. 如果 virtualKeyboardPolicy 不是 manual 或 inputMode 的 属性值为 none ，则中止这些步骤。
5. 调用系统 API 显示 VK。
6. 并行 执行以下步骤：
   1. 等待系统显示虚拟键盘。
   2. 调用 设置虚拟键盘边界矩形， 使用键盘的操作系统报告的边界矩形和文档的 视口 矩形。
   3. 触发一个名为 "geometrychange" 的事件 在此。

hide() 方法

该方法必须按照以下步骤执行：

1. 令 window 为 this 的 相关全局对象。断言 window 是 Window 对象。
2. 如果 window 没有 粘性激活，则中止这些步骤。
3. 如果焦点元素的 virtualKeyboardPolicy 不是 manual 或 inputMode 的 属性值为 none ，则中止这些步骤。
4. 调用系统 API 隐藏 VK。
5. 并行 执行以下步骤：
   1. 等待系统隐藏虚拟键盘。
   2. 调用 设置虚拟键盘边界矩形 ，使用键盘的操作系统报告的边界矩形（全为 0 值）和 文档 的 视口 矩形。
   3. 触发一个名为 "geometrychange" 的事件 在此。

注意

平台启发式方法可能会对 VK 的show() 和 hide() 施加额外限制。例如，在 Windows 上，指针类型必须为触摸或笔。

注意

一些人对显示担忧，关于 show() 和 hide() 方法不是基于 Promise 的，但我们认为 Web 开发者使用 ongeometrychange 事件的设计更好，因为它在 VK 可见性变化时触发，使返回值不必要。

overlaysContent

overlaysContent getter 步骤为返回 this 的 overlaysContent。

overlaysContent setter 步骤为将 this 的 overlaysContent 设置为给定值。

boundingRect

该属性报告 VK 与文档的 视口 在客户端坐标中的交集。调用 设置虚拟键盘边界矩形。

设置虚拟键盘边界矩形

设置虚拟键盘边界矩形，使用 osk（表示屏幕键盘矩形的 DOMRect）和 lv（表示 文档的 视口 矩形的 DOMRect）作为输入，按以下步骤运行：

1. 令 osk 为屏幕键盘矩形，运行算法后得到的结果是show() 或 hide()。
2. 令 lv 为运行算法后得到的文档的 视口矩形show() 或 hide()。
3. 将 osk 映射到 lv 的坐标空间。
4. 令 bounds 为 DOMRect 对象。
5. 通过将 lv 与 osk 相交来更新 bounds。
6. 将 bounds 映射到 lv 的坐标空间。
7. 返回 bounds。

boundingRect getter 步骤为返回 this 的 boundingRect。

ongeometrychange

当 VK 与文档的视口的交集发生变化时（例如，响应 VK 显示或隐藏或浏览器窗口重新定位），会调度该事件。

WebIDL partial interface mixin ElementContentEditable {
         [CEReactions] attribute DOMString virtualKeyboardPolicy;
    };

virtualKeyboardPolicy 是一个枚举属性，其关键字包括 empty string、auto 和 manual。IDL 属性必须反映同名的相应内容属性。 当指定在内容可编辑的主机元素上时，auto 会使相应的可编辑元素在聚焦或点击时自动显示 VK，而 manual 会将可编辑元素的焦点和点击与 VK 的当前状态分离——VK 保持原状。
除非从 auto 更改为 empty string 或反之，否则任何virtualKeyboardPolicy 属性值的更改都会否定当前定义的行为。

• 当设置 auto 枚举属性时，VK 由浏览器处理。
• 当设置 manual 枚举属性时，它会阻止浏览器的默认 VK 处理，需要由脚本处理。
• 当设置 empty string 枚举属性时，VK 由浏览器处理。

VirtualKeyboard API 提议了六个新的 CSS 环境变量，Web 开发人员可以利用这些变量来计算虚拟键盘的大小，并以声明方式调整布局。