Get Installed Related Apps API 允许网页应用检测与之相关的应用是否已在本地设备下载

支持检测的应用包括通用 Window 应用 Android 应用或 PWA 应用

使用 API

调用 Navigator 接口上的 getInstalledRelatedApps() 方法以使用该 API

方法返回一个 Promise 的相关应用信息数组

id 项代表应用的 ID，具体格式受不同操作系统而有所不同

url 项代表与应用相关的 URL

version 项代表与应用相关的版本

platform 项代表应用的操作系统类型，可能是 chrome_web_store play chromeos_play webapp windows f-droid amazon 之一

方法抛出 InvalidStateError 错误，若未在顶层浏览器上下文中调用

1
2
3
4
5
6
7
8

const apps = await navigator.getInstalledRelatedApps()

for (const app of apps) {
  console.log(app.id)
  console.log(app.url)
  console.log(app.version)
  console.log(app.platform)
}

方法必须在顶层文档上下文中调用，且要求必须处于严格上下文环境中

背景要求

当前网页应用需要在 manifest 文件中指定 related_applications 字段

本地应用需要与网页应用存在某种形式的联系，如：

Android 应用通过 Digital Asset Links system 实现

Window 应用通过 URI Handlers 实现

PWA 应用通过其 manifest 文件中定义的 related_applications 字段或 /.well-known/assetlinks.json 文件定义

类型

1
2
3
4
5
6
7
8
9
10

interface Navigator {
  getInstalledRelatedApps(): Promise<RelatedApplication[]>
}

interface RelatedApplication {
  platform: string
  url?: string
  id?: string
  version?: string
}

链接

• https://wicg.github.io/get-installed-related-apps/spec/

Web Share API 允许分享文字、链接、文件或其他内容到用户指定的分享目标

分享操作

使用 Navigator 接口上的 share() 方法分享内容

方法允许传递一组可选的分享内容，包括 title 字段；text 字段；url 字段；files 字段

方法返回一个 Promise

方法可能抛出 InvalidStateError 异常，若当前文档未处于活跃状态；或当前存在其他分享操作

方法可能抛出 NotAllowedError 异常，若当前未被授予 web-share 权限；或分享操作未因用户交互行为调用；或分享的文件因为隐私问题被拒绝

方法可能抛出 TypeError 异常，若校验分享数据失败

title text url files 四个字段均为空

仅存在 files 字段且其为空数组

用户代理实现不支持分享文件

用户代理确信任一分享的文件存在恶意行为

存在 url 字段且解析 URL 失败

存在 url 字段且其协议不是可分享的协议类型，如 http https 等；或为不可分享的协议类型，如 file、ws、wss、javascript 或本地协议等

方法可能抛出 AbortError 异常，若用户代理无法获取到可用的分享目标；或用户退出选取分享目标过程

方法可能抛出 DataError 异常，若尝试启动分享目标失败；或传递分享数据失败

检测分享

使用 Navigator 接口上的 canShare() 方法检测内容能否被成功分享，传递的参数同 share() 方法，返回一个 boolean

通常在调用 share() 方法之前先行调用该方法以检测能否成功分享

若调用 share() 方法会成功，则 canShare() 方法一定返回 true；反之返回 false

权限策略

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

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

类型

1
2
3
4
5
6
7
8
9
10
11

interface Navigator {
  share(data?: ShareData): Promise<undefined>
  canShare(data?: ShareData): boolean
}

interface ShareData {
  files?: File[]
  title?: string
  text?: string
  url?: string
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Web_Share_API
• https://w3c.github.io/web-share/

VirtualKeyboard API 允许控制设备的虚拟键盘的几何信息和展示及隐藏（特别是针对平板、智能手机等无法提供机械键盘的设备）

通过 navigator.virtualKeyboard 暴露的 VirtualKeyboard 接口实例使用

虚拟键盘展示隐藏

VirtualKeyboard 接口的 show() 方法展示虚拟键盘

VirtualKeyboard 接口的 hide() 方法隐藏虚拟键盘

VirtualKeyboard 接口的 geometrychange 事件在虚拟键盘的可见性变化或浏览器窗口重定位时触发，返回一个 Event 事件，通常使用该事件来监听具体虚拟键盘的可见性的时机

1
2
3
4
5
6
7

navigator.virtualKeyboard.show()

navigator.virtualKeyboard.hide()

navigator.virtualKeyboard.addEventListener('geometrychange', (e) => {
    //
})

需要在因为用户交互产生的行为中调用

需要当前聚焦元素的 virtualkeyboardpolicy 属性指定为 manual 或 inputmode 指定为除 none 之外的其他值

其中 show() 方法额外需要当前聚焦的元素为表单元素或者当前聚焦元素需要指定 contenteditable 属性为 true

虚拟键盘几何位置信息

VirtualKeyboard 接口的 boundingRect 只读属性给出虚拟键盘的几何位置信息，返回一个 DOMRect，默认值均设置为 0

1

navigator.virtualKeyboard.boundingRect

同时 CSS 环境变量 keyboard-inset-top keyboard-inset-right keyboard-inset-bottom keyboard-inset-left keyboard-inset-width keyboard-inset-height 可以通过 env() CSS 函数使用

1
2
3
4
5
6

env(keyboard-inset-top)
env(keyboard-inset-right)
env(keyboard-inset-bottom)
env(keyboard-inset-left)
env(keyboard-inset-width)
env(keyboard-inset-height)

管理虚拟键盘几何位置

VirtualKeyboard 接口的 overlaysContent 属性用于指定虚拟键盘的几何位置策略，返回一个 boolean，默认 false

1

navigator.virtualKeyboard.overlaysContent

将该值设定为 true 以阻止浏览器默认的虚拟键盘调度策略，从而允许利用相关的 API 属性方法和 CSS 环境变量自定义地调整网页的布局

指定元素的虚拟键盘策略

全局 virtualkeyboardpolicy 属性用于指定特定元素的虚拟键盘策略，默认为空字符串

指定为空字符串或 auto 表示使用默认的虚拟键盘策略

指定为 manual 表示阻止使用默认的虚拟键盘策略

接口

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

interface ElementContentEditable {
  virtualKeyboardPolicy: '' | 'auto' | 'manual'
}

interface VirtualKeyboard extends EventTarget {
  show(): void
  hide(): void
  readonly boundingRect: DOMRect
  overlaysContent: boolean
  ongeometrychange: ((this: VirtualKeyboard, ev: Event) => any) | null
}

interface Navigator {
  readonly virtualKeyboard: VirtualKeyboard
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/VirtualKeyboard_API
• https://w3c.github.io/virtual-keyboard/

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/