Keyboard API

在此页

Keyboard API concepts and usage
接口
规范
浏览器兼容性
相关话题

这是实验性技术
检查浏览器兼容性表格要小心谨慎在生产中使用这之前。

The Keyboard API provides methods for working with a physical keyboard that is attached to a device running a browser. It provides several capabilities. Keyboard mapping provides an interface for retrieving the string generated by particular physical key on a keyboard to correctly identify that key to a user. Keyboard locking enables a web page to capture keys that are normally reserved by the user agent or the underlying operating system. The intended use of the Keyboard API is by web applications such as games or remote access apps that provide a full-screen immersive experience.

Keyboard API concepts and usage

Keyboard mapping

On physical keyboards, the code attribute contains the physical location of the key that was pressed, and the key attribute contains the string generated by pressing the key at that physical location on the keyboard. The key value takes into account the keyboard's locale (for example, 'en-US'), layout (for example, 'QWERTY'), and modifier-key state (Shift, Control, etc.). Historically there has been no way to retrieve that information.

The Keyboard Map API provides a way to retrieve the string generated by a particular key press, through the 键盘 interface and the KeyboardLayoutMap 接口。 键盘 interface is accessed through navigator.keyboard . 键盘 提供 Keyboard.getLayoutMap method, which returns a promise that resolves with a KeyboardLayoutMap object that contains members for converting codes to keys. A list of valid code values is found in the Writing System Keys 章节的 UI Events KeyboardEvent code Values spec.

The following example demonstrates how to get the location-specific or layout-specific string associated with the key labeled W on an English QWERTY keyboard.

if (navigator.keyboard) {
  var keyboard = navigator.keyboard;
  keyboard.getLayoutMap()
  .then(keyboardLayoutMap => {
    var upKey = keyboardLayoutMap.get('KeyW');
    window.alert('Press ' + upKey + ' to move up.');
  });
} else {
  // Do something else.
}

Keyboard locking

Richly interactive web pages, games, and remote-streaming experiences often require access to special keys and keyboard shortcuts while in full-screen mode. Examples of such key/key combinations include Escape, Alt+Tab, and Ctrl+N. Those keys and key combinations are typically captured by the user agent or the underlying operating system, as illustrated in the following example.

To capture the "W", "A", "S", and "D" keys, call lock() with a list that contains the key code attribute value for each of these keys:

navigator.keyboard.lock(["KeyW", "KeyA", "KeyS", "KeyD"]);

This captures these keys regardless of which modifiers are used with the key press. Assuming a standard United States QWERTY layout, registering KeyW ensures that "W", Shift+"W", Control+"W", Control+Shift+"W", and all other key modifier combinations with "W" are sent to the app. The same applies to for KeyA , KeyS and KeyD .

Writing system keys

The codes passed Keyboard.lock and the various methods of the KeyboardLayoutMap interface are called “writing system keys”.

“Writing system keys” are defined in the Writing System Keys 章节的 UI Events KeyboardEvent code Values spec as the physical keys that change meaning based on the current locale and keyboard layout. These keys are shown below. Blue keys are present on all standard keyboards while green keys are only available on some keyboards.

Writing system keys as defined by the UI Events KeyboardEvent code Values spec.

接口

键盘
KeyboardLayoutMap
navigator.keyboard 只读: 返回 键盘 object which provides access to functions that retrieve keyboard layout maps and toggle capturing of key presses from the physical keyboard.

规范

规范	状态	注释
Keyboard Map	编者草案	初始定义。
Keyboard Lock	编者草案	初始定义。

浏览器兼容性

The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.

更新 GitHub 上的兼容性数据

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`键盘`	Chrome 68	Edge 79	Firefox No	IE No	Opera 55	Safari No	WebView Android No	Chrome Android No	Firefox Android No	Opera Android No	Safari iOS No	Samsung Internet Android No
`getLayoutMap`	Chrome 69	Edge 79	Firefox No	IE No	Opera 56	Safari No	WebView Android No	Chrome Android No	Firefox Android No	Opera Android No	Safari iOS No	Samsung Internet Android No
`lock`	Chrome 68	Edge 79	Firefox No	IE No	Opera 55	Safari No	WebView Android No	Chrome Android No	Firefox Android No	Opera Android No	Safari iOS No	Samsung Internet Android No
`unlock`	Chrome 68	Edge 79	Firefox No	IE No	Opera 55	Safari No	WebView Android No	Chrome Android No	Firefox Android No	Opera Android No	Safari iOS No	Samsung Internet Android No

图例

完整支持
不支持
实验。期望将来行为有所改变。

Keyboard lock API