Keyboard Map API 允许获取键盘按键码至键盘按键名的映射

通过 navigator.keyboard 暴露的 Keyboard 接口实例使用

获取键盘映射

Keyboard 接口的 getLayoutMap() 方法提供了获取键盘映射的方法

方法返回一个 Promise 的 KeyboardLayoutMap 实例

1
2
3
4

navigator.keyboard.getLayoutMap().then((layoutMap) => {
  const code = 'KeyW'
  const key = layoutMap.get(code)
})

KeyboardLayoutMap 接口反映了一组键值对对象，键名为键盘按键码，键值为键盘按键名；它是一个只读的类 map 对象

键盘映射更改

Keyboard 接口的 layoutchange 事件在键盘映射改变时触发

该事件尚未得到主流浏览器的支持

权限策略

该 API 调用受到 keyboard-map 权限策略的控制，可以通过 Permissions-Policy 响应头指定，或通过 <iframe> 标签的 allow 属性指定

默认为 self，即允许在当前上下文或内嵌的其他同源上下文中使用

类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

interface Keyboard extends EventTarget {
  lock(keyCodes?: string[]): Promise<void>
  unlock(): void
}

interface Navigator {
  readonly keyboard: Keyboard
}

interface KeyboardLayoutMap {
  forEach(callbackfn: (value: string, key: string, map: Map<string, string>) => void, thisArg?: any): void
  get(key: string): string | undefined
  has(key: string): boolean
  readonly size: number
  entries(): IterableIterator<[string, string]>
  keys(): IterableIterator<string>
  values(): IterableIterator<string>
  [Symbol.iterator](): IterableIterator<[string, string]>
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Keyboard_API
• https://wicg.github.io/keyboard-map/

EyeDropper API 提供了吸管工具，允许用户选择屏幕上的某个特定位置的颜色

该 API 仅在严格上下文环境下允许使用

使用

EyeDropper() 构造函数用于创建一个 eyedropper 工具

调用 EyeDropper 接口的 open() 方法以选择颜色

方法接受一个可选的配置项，其唯一可选属性 signal 是一个 AbortSignal，可用于编程式退出选择过程

方法返回一个 Promise 的对象，其唯一属性 sRGBHex 代表一个相应的十六进制的颜色字符串

方法可能抛出 NotAllowedError，若方法不是因为用户交互触发的

方法可能抛出 InvalidStateError，若当前已存在其他打开的 EyeDropper

方法可能抛出 AbortError，若用户退出选择颜色或因调用 AbortSignal.abort() 方法退出

方法可能抛出 OperationError，若因为除用户主动退出之外的原因导致获取颜色信息失败

1
2
3
4
5
6
7
8
9
10
11
12
13

try {
  const eyeDropper = new EyeDropper()

  const controller = new AbortController()

  const { sRGBHex } = await eyeDropper.open({
    signal: controller.signal,
  })

  console.log(sRGBHex)
} catch (err) {
  console.error(err)
}

示例

类型

1
2
3
4
5
6
7
8
9
10
11
12

interface ColorSelectionResult {
  sRGBHex: string
}

interface ColorSelectionOptions {
  signal: AbortSignal
}

interface EyeDropper {
  constructor()
  open(options: ColorSelectionOptions): Promise<ColorSelectionResult>
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper_API
• https://wicg.github.io/eyedropper-api/

Network Information API 允许获取网络信息和监听网络信息更改，以及 Save Data API 提供了侦测用户流量使用倾向的方法

通过 navigator.connection 暴露 NetworkInformation 实例使用

获取网络信息

NetworkInformation 接口的 type 属性表示当前的网络连接的类型

NetworkInformation 接口的 effectiveType 属性表示当前的网络连接的状态

NetworkInformation 接口的 downlink 属性表示当前的 downlink 速度

NetworkInformation 接口的 downlinkMax 属性表示当前最大的 downlink 速度

NetworkInformation 接口的 rtt 属性表示当前的 RTT 参数

1
2
3
4
5

const type = navigator.connection.type
const effectiveType = navigator.connection.effectiveType
const downlink = navigator.connection.downlink
const downlinkMax = navigator.connection.downlinkMax
const rtt = navigator.connection.rtt

监听网络信息

NetworkInformation 接口的 change 事件在网络信息更新时触发

1

navigator.connection.addEventListener('change', () => { /* to do something */ })

类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

interface Navigator {
  readonly connection: NetworkInformation
}

interface WorkerNavigator {
  readonly connection: NetworkInformation
}

interface NetworkInformation extends EventTarget {
  readonly type: ConnectionType
  readonly effectiveType: EffectiveConnectionType
  readonly downlinkMax: number
  readonly downlink: number
  readonly rtt: number
  readonly saveData: boolean
  onchange: ((this: NetworkInformation, ev: Event) => any) | null
}

interface NetworkInformationEventMap {
  change: Event
}

type ConnectionType = 'bluetooth' | 'cellular' | 'ethernet' | 'none' | 'wifi' | 'wimax' | 'other' | 'unknown'

type EffectiveConnectionType = 'slow-2g' | '2g' | '3g' | '4g'

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API
• https://wicg.github.io/netinfo/

Picture-in-Picture API 允许某个特定的视频元素管理画中画模式

启用画中画模式

通过调用 HTMLVideoElement 接口上的 requestPictureInPicture() 方法以启用画中画模式

方法返回一个 Promise 的 PictureInPictureWindow

方法可能抛出 SecurityError 异常，如当前特性被 Permission Policy 拒绝

1

element.requestPictureInPicture()

停止画中画模式

通过调用 Document 接口上的 exitPictureInPicture() 方法以停止画中画模式

方法返回一个 Promise

1

document.exitPictureInPicture()

画中画模式信息

HTMLVideoElement 接口上的 disablePictureInPicture 属性反映了当前视频元素的画中画模式是否可用，返回 boolean 值

Document 接口上的 pictureInPictureEnabled 只读属性反映了当前文档的画中画模式是否可用，返回 boolean 值

Document 接口或 ShadowRoot 接口上的 pictureInPictureElement 只读属性反映了当前处于画中画模式的元素，返回 Element 值或 null 值

HTMLVideoElement 接口上的 enterpictureinpicture 事件在当前元素成功启用画中画模式时触发，返回一个 PictureInPictureEvent 事件

HTMLVideoElement 接口上的 leavepictureinpicture 事件在当前元素成功停止画中画模式时触发，返回一个 PictureInPictureEvent 事件

PictureInPictureEvent 事件继承自 Event 事件，其唯一额外 pictureInPictureWindow 只读属性代表当前事件相关的 PictureInPictureWindow 实例

PictureInPictureWindow 接口反映了当前的画中画模式窗口，其 width 只读属性和 height 只读属性反映了窗口的宽高，其 resize 事件在窗口尺寸改变时触发并返回一个 PictureInPictureEvent 事件

权限策略

该 API 调用受到 picture-in-picture 权限策略的控制，可以通过 Permissions-Policy 响应头指定，或通过 <iframe> 标签的 allow 属性指定

默认值是 *，即允许任意源的浏览上下文使用该 API

类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

interface Document {
  readonly pictureInPictureElement: Element | null
  readonly pictureInPictureEnabled: boolean
  exitPictureInPicture(): Promise<void>
}

interface ShadowRoot {
  readonly pictureInPictureElement: Element | null
}

interface HTMLVideoElement {
  disablePictureInPicture: boolean
  requestPictureInPicture(): Promise<PictureInPictureWindow>
  onenterpictureinpicture: ((this: HTMLVideoElement, ev: PictureInPictureEvent) => any) | null
  onleavepictureinpicture: ((this: HTMLVideoElement, ev: PictureInPictureEvent) => any) | null
}

interface PictureInPictureEvent extends Event {
  readonly pictureInPictureWindow: PictureInPictureWindow
}

interface PictureInPictureWindow extends EventTarget {
  readonly width: number
  readonly height: number
  onresize: ((this: PictureInPictureWindow, ev: PictureInPictureEvent) => any) | null
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API
• https://w3c.github.io/picture-in-picture/

Fullscreen API 允许某个特定的元素管理全屏模式

启用全屏模式

通过调用 Element 接口上的 requestFullscreen() 方法以启用全屏模式

方法传入一个可选的配置项，其唯一 navigationUI 可选参数控制是否展示 navigation UI，值为 "auto" "show" "hide" 之一，默认值为 "auto"

方法返回一个 Promise

方法可能抛出 TypeError 异常，如当前文档并非处于活跃状态、当前元素未处于文档中、当前元素不允许使用全屏模式、当前元素是一个激活的 popover 元素、当前元素是 <dialog> 元素、当前元素不是 HTML SVG MathML 元素等等

1

element.requestFullscreen()

停止全屏模式

通过调用 Document 接口上的 exitFullscreen() 方法以停止全屏模式

方法返回一个 Promise

1

document.exitFullscreen()

全屏模式信息

Document 接口上的 fullscreenEnabled 属性反映了全屏模式是否可用，返回 boolean 值

Document 接口或 ShadowRoot 接口上的 fullscreenElement 属性反映了当前处于全屏模式的元素，返回 Element 值或 null 值

Document 接口或 Element 接口上的 fullscreenchange 事件在文档或元素的全屏状态改变时触发，返回一个 Event 事件

Document 接口或 Element 接口上的 fullscreenerror 事件在文档或元素的全屏状态改变失败时触发，返回一个 Event 事件

通常，监听 Web 程序内的全屏状态改变，通过监听 Document 接口上的即可，文档内元素的相应事件会冒泡至文档

权限策略

该 API 调用受到 fullscreen 权限策略的控制，可以通过 Permissions-Policy 响应头指定，或通过 <iframe> 标签的 allow 属性指定

默认为 self，即允许在当前上下文或内嵌的其他同源上下文中使用

类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

interface Document {
  readonly fullscreenElement: Element | null
  readonly fullscreenEnabled: boolean
  exitFullscreen(): Promise<void>
  onfullscreenchange: ((this: Document, ev: Event) => any) | null
  onfullscreenerror: ((this: Document, ev: Event) => any) | null
}

interface ShadowRoot {
  readonly fullscreenElement: Element | null
}

interface Element {
  requestFullscreen(options?: FullscreenOptions): Promise<void>
  onfullscreenchange: ((this: Element, ev: Event) => any) | null
  onfullscreenerror: ((this: Element, ev: Event) => any) | null
}

interface FullscreenOptions {
  navigationUI?: FullscreenNavigationUI
}

type FullscreenNavigationUI = 'auto' | 'hide' | 'show'

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API
• https://fullscreen.spec.whatwg.org/

Keyboard Lock API 允许控制键盘的输入形式，捕获键盘的输入从而进行自定义的处理（特别是针对一些特殊按键）

通过 navigator.keyboard 暴露的 Keyboard 接口实例使用

该 API 的使用要求有用户交互的发生

启用键盘锁定

使用 Keyboard 接口的 lock() 方法启用键盘锁定

方法可以传递一个可选的 keyCodes 字符串数组参数，代表要锁定的键值码；不传递则代表锁定所有的按键

方法返回一个 Promise

方法可能抛出 AbortError，若在该方法完成前又重新调用了该方法

方法可能抛出 InvalidAccessError，若任一 keyCodes 中的项非法

方法可能抛出 InvalidStateError，若方法未在活跃浏览器上下文中调用

1
2

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

若调用多次调用 lock() 方法且中途未调用 unlock() 方法，则只有最后一次指定的 keyCodes 有效

停止键盘锁定

使用 Keyboard 接口的 unlock() 方法停止键盘锁定

1

navigator.keyboard.unlock()

类型

1
2
3
4
5
6
7
8

interface Keyboard extends EventTarget {
  lock(keyCodes?: string[]): Promise<void>
  unlock(): void
}

interface Navigator {
  readonly keyboard: Keyboard
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Keyboard_API
• https://wicg.github.io/keyboard-lock/

Pointer Lock API 允许控制鼠标的输入形式，将鼠标的移动从光标位置移动转换为自定义的形式（同时隐藏光标）

指针锁定与鼠标捕获比较类似，但其是持久的，即不会自动释放鼠标；并且其不受浏览器边界的限制；最大特点是，其会隐藏光标

启用指针锁定

通过调用对应 Element 接口上的 requestPointerLock() 方法以启用指针锁定

方法默认无参数，新提案支持传入一组配置项，唯一参数 unadjustedMovement 指定是否启用操作系统级别的鼠标位置适配，目前为部分浏览器支持

方法默认无返回值，但新提案支持返回 Promise，目前为部分浏览器支持

方法调用要求存在用户交互且为活跃文档，并且不允许连续调用该方法，并且 <iframe> 标签中的调用需要设置允许 allow-pointer-lock 沙箱策略并且除 该<iframe> 标签之外的其他 <iframe> 标签必须未处于指针调用状态，否则调用会失败

1

el.requestPointerLock()

停止指针锁定

通过调用 Document 接口上的 exitPointerLock() 方法以停止指针锁定

1

document.exitPointerLock()

指针锁定信息

Document 接口或 ShadowRoot 接口的 pointerLockElement 属性返回当前启用指针锁定的元素，若不存在则返回 null

Document 接口的 pointerlockchange 事件在指针锁定状态改变时触发，返回一个 Event 事件

Document 接口的 pointerlockerror 事件在指针锁定状态改变失败时触发，返回一个 Event 事件’

MouseEvent 接口的 movementX 属性与 movementY 属性仅在 mousemove 事件中可用，反映了前后两个 mousemove 事件的鼠标移动的坐标

沙箱策略

该 API 在 <iframe> 标签中的调用受到 allow-pointer-lock 沙箱策略的控制，需要将 sandbox 的属性指定为允许

类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

interface Document {
  exitPointerLock(): void
  onpointerlockchange: ((this: Document, ev: Event) => any) | null
  onpointerlockerror: ((this: Document, ev: Event) => any) | null
}

interface DocumentOrShadowRoot {
  readonly pointerLockElement: Element | null
}

interface Element {
  requestPointerLock(): void
}

interface MouseEvent {
  readonly movementX: number
  readonly movementY: number
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API
• https://w3c.github.io/pointerlock/

Screen Wake Lock API 允许控制设备的屏幕变暗、休眠或锁定的策略

通过 navigator.wakeLock 暴露的 WakeLock 接口实例使用

启用屏幕管理策略

通过 WakeLock 接口的 request() 方法来请求启用屏幕管理策略

方法传入一个可选的 type 字符串参数，唯一允许值为 'screen'

方法返回一个 Promise 的 WakeLockSentinel 实例

方法可能抛出一个 NotAllowedError 异常，例如被 Permissions Policy 拒绝、当前网页未处于活跃状态、当前网页处于隐藏状态或用户代理无法获取到系统的屏幕管理策略

1

const sentinel = await navigator.wakeLock.request()

释放屏幕管理策略

通过 WakeLockSentinel 接口的 release() 方法来手动关闭屏幕管理策略

方法返回一个 Promise

1

sentinel.release()

同时，操作系统可能会在网页失去焦点或隐藏时自动关闭屏幕管理策略

屏幕管理策略信息

WakeLockSentinel 接口的 released 属性返回一个 boolean，表示当前 WakeLockSentinel 是否已被释放

WakeLockSentinel 接口的 type 属性返回一个 string，表示当前 WakeLockSentinel 的类型

WakeLockSentinel 接口的 release 事件，在 WakeLockSentinel 被释放时触发，返回一个 Event 事件

权限策略

该 API 调用受到 screen-wake-lock 权限策略的控制，可以通过 Permissions-Policy 响应头指定，或通过 <iframe> 标签的 allow 属性指定

默认为 self，即允许在当前上下文或内嵌的其他同源上下文中使用

类型

1
2
3
4
5
6
7
8
9
10
11
12

interface WakeLock {
  request(type?: WakeLockType): Promise<WakeLockSentinel>
}

interface WakeLockSentinel extends EventTarget {
  onrelease: ((this: WakeLockSentinel, ev: Event) => any) | null
  readonly released: boolean
  readonly type: WakeLockType
  release(): Promise<void>
}

type WakeLockType = 'screen'

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API
• https://w3c.github.io/screen-wake-lock/

Battery Status API 提供了访问设备电源信息和监听电源信息变化的功能，可以用于动态根据用户设备的电源情况调整一些功能的策略

获取电源管理实例

使用 Navigator 接口的 getBattery() 方法获取到电源管理实例，方法返回一个 Promise 的 BatteryManager 实例

1

const batteryManager = await navigator.getBattery()

获取设备电源信息

BatteryManager 接口提供了访问设备电源信息的属性

BatteryManager 接口的 charging 属性返回一个 boolean，表示当前设备是否处于充电状态

BatteryManager 接口的 chargingTime 属性返回一个 number，表示当前设备充电完成所需的充电时间，若设备已充满或无法获取电源信息则返回 0，若设备未处于充电状态则返回 +Infinity

BatteryManager 接口的 dischargingTime 属性返回一个 number，表示当前设备至完全耗尽电量的时间，若设备处于充电状态或无法获取电源信息则返回 +Infinity

BatteryManager 接口的 level 属性返回一个范围从 0.0 到 1.0 之间的 number，表示当前设备电源的电量百分比，若无法获取电源信息则返回 1.0

1
2
3
4

batteryManager.charging
batteryManager.chargingTime
batteryManager.dischargingTime
batteryManager.level

监听设备电源信息更新

BatteryManager 接口提供了监听设备电源信息变化的事件

BatteryManager 接口的 chargingchange 事件在电源充电状态改变时触发，即 charging 属性改变时触发

BatteryManager 接口的 chargingtimechange 事件在电源充电完成时间改变时触发，即 chargingTime 属性改变时触发

BatteryManager 接口的 dischargingtimechange 事件在电源电量耗尽时间改变时触发，即 dischargingTime 属性改变时触发

BatteryManager 接口的 levelchange 事件在电源电量改变时触发，即 level 属性改变时触发

1
2
3
4
5
6
7
8
9
10
11
12

batteryManager.addEventListener('chargingchange', () => {
  console.log(batteryManager.charging)
})
batteryManager.addEventListener('chargingtimechange', () => {
    console.log(batteryManager.chargingTime)
})
batteryManager.addEventListener('dischargingtimechange', () => {
    console.log(batteryManager.dischargingTime)
})
batteryManager.addEventListener('levelchange', () => {
    console.log(batteryManager.level)
})

权限策略

该 API 受 battery 权限策略的限制（无论是通过 Permissions-Policy 响应头指定抑或是通过 iframe 元素的 allow 属性指定）

默认为 self，即允许在当前上下文或内嵌的其他同源上下文中使用

类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14

interface Navigator {
  getBattery: () => Promise<BatteryManager>
}

interface BatteryManager extends EventTarget {
  readonly charging: boolean
  readonly chargingTime: number
  readonly dischargingTime: number
  readonly level: number
  onchargingchange: ((this: BatteryManager, ev: Event) => any) | null
  onchargingtimechange: ((this: BatteryManager, ev: Event) => any) | null
  ondischargingtimechange: ((this: BatteryManager, ev: Event) => any) | null
  onlevelchange: ((this: BatteryManager, ev: Event) => any) | null
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API
• https://w3c.github.io/battery/

Web Storage API 可用于保存键值对形式的数据，包括 localStorage 和 sessionStorage 两种，键值对均要求为字符串（非字符串类型数据会隐式转换为字符串）

sessionStorage 会话存储的数据仅在当前会话中有效，若关闭标签页或浏览器则会失效

localStorage 本地存储的数据长期有效

Web Storage API 同样受同源策略限制，不同源的 Storage 无法共享

Storage 的获取

通过 window.sessionStorage 访问会话存储对应的 Storage 实例

通过 window.localStorage 访问本地存储对应的 Storage 实例

Storage 的操作

Storage 接口提供了一些对会话存储或本地存储的操作方法

读取键值对

Storage 接口的 getItem() 方法用于获取指定键名对应的键值，若数据不存在则返回 null

1

window.localStorage.getItem('k')

设置键值对

Storage 接口的 setItem() 方法用于设置键值对

1

window.localStorage.setItem('k', 'v')

清除键值对

Storage 接口的 removeItem() 方法用于移除指定键名对应的键值

1

window.localStorage.removeItem('k')

清空存储

Storage 接口的 clear() 方法用于清除整个存储

1

window.localStorage.clear()

其他

Storage 接口的 length 属性返回存储的长度

Storage 接口支持直接使用键名索引来获取或设置对应的键值，支持直接使用 delete 关键字移除对应的键值

Storage 接口的 key() 方法用于获取指定索引的值，索引的顺序是由浏览器决定的，因此该顺序是不可靠的，若数据不存在则返回 null

1
2
3
4
5
6
7
8

window.localStorage.length
window.localStorage.k
window.localStorage['k']
window.localStorage.k = 'v'
window.localStorage['k'] = 'v'
delete window.localStorage.k
delete window.localStorage['k']
window.localStorage.key(0)

存储更改

会话存储或本地存储的更改会在与之同域的会话中触发全局 Window 的 storage 事件，并返回一个 StorageEvent 事件

StorageEvent 事件的 storageArea 属性返回存储变化的 Storage 实例

StorageEvent 事件的 url 属性返回存储变化的文档的 URL

StorageEvent 事件的 key 属性返回存储变化的键名

StorageEvent 事件的 oldValue 属性返回存储变化的原键值或 null

StorageEvent 事件的 newValue 属性返回存储变化的现键值或 null

1
2
3
4
5
6
7

window.addEventListener('storage', (e) => {
  console.log(e.key)
  console.log(e.oldValue)
  console.log(e.newValue)
  console.log(e.url)
  console.log(e.storageArea)
})

类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

interface Window {
  readonly localStorage: Storage
  readonly sessionStorage: Storage
  onstorage: ((this: WindowEventHandlers, ev: StorageEvent) => any) | null
}

interface Storage {
  readonly length: number
  clear(): void
  getItem(key: string): string | null
  key(index: number): string | null
  removeItem(key: string): void
  setItem(key: string, value: string): void
  [name: string]: any
}

interface StorageEvent extends Event {
  readonly key: string | null
  readonly newValue: string | null
  readonly oldValue: string | null
  readonly storageArea: Storage | null
  readonly url: string
  initStorageEvent(type: string, bubbles?: boolean, cancelable?: boolean, key?: string | null, oldValue?: string | null, newValue?: string | null, url?: string | URL, storageArea?: Storage | null): void
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API
• https://html.spec.whatwg.org/multipage/webstorage.html