Payment Handler API 允许网站直接处理支付请求，而非重定向至额外的页面处理支付请求

网站可以使用 Payment Request API 创建支付请求，随后交由 Payment Handler API 处理，如寻找可用于支付的 APP、将它们作为可选的选项提供给用户、当用户选定后打开支付窗口以便用户输入支付细节以及与支付 APP 交互

基本流程

创建支付请求

通常首先调用 PaymentRequest() 构造方法创建一个支付请求

在支持的浏览器中，会根据传入的 supportedMethods 参数去请求对应的支付方式 manifest 文件

默认首先检测响应是否包含 Link 响应头，并且响应头是否包含 rel="payment-method-manifest"，那么将利用该参数指定的 URL 下载对应的资源解析后作为 manifest 文件

否则将解析响应，并将结果作为支付方式 manifest 文件

该支付方式 manifest 文件通常需要包含 default_applications 字段和 supported_origins 字段

default_applications 字段表示支付应用的默认来源（通常是应用的 manifest 文件），在目标应用未下载时使用

supported_origins 字段表示允许代替当前支付应用处理当前支付请求的其他支付应用，在目标应用未下载且列表中应用已下载时替代使用

两字段均接收字符串数组

支付可用性

此时或之前调用 PaymentRequest 接口的 canMakePayment() 方法，检测对应支付方式是否可用（如支付方式被发现，处理支付方式的 APP 已下载或基于网络的支付应用已注册）

在 Payment Handler API 中，增加了触发在 ServiceWorkerGlobalScope 中的 canmakepayment 事件，该事件会在调用 PaymentRequest() 构造方法之后于对应支付应用注册的 Service Worker 中触发

在此事件回调中，可以调用 CanMakePaymentEvent 事件的 respondWith() 方法自定义支付方式的是否支持的信息

处理支付

随后在与用户发生交互后，调用 PaymentRequest 接口的 show() 方法显示浏览器提供的支付方式选择页面，此过程中会使用到支付方式 manifest 文件的 name 字段和 icons 字段

调用该方法之后，会在 ServiceWorkerGlobalScope 中触发 paymentrequest 事件，从而可以开始进行处理支付请求

如可以调用 PaymentRequestEvent 事件的 openWindow() 方法打开支付方式页面，用于用户填写支付请求信息

亦可以调用 PaymentRequestEvent 事件的 respondWith() 方法将支付请求执行结果返回给用户

管理支付

可以通过 ServiceWorkerRegistration 接口的 paymentManager 只读属性暴露的 PaymentManager 实例

如设置 userHint 属性向浏览器提供提示信息，可以在展示支付支付方式页面时显示

亦如调用 enableDelegations() 方法设置委托支付应用收集而非交由浏览器收集的支付信息

支付可用性

ServiceWorkerGlobalScope 中的 canmakepayment 事件在支付应用能够提供服务时，在其 Service Worker 中触发，返回一个 CanMakePaymentEvent 事件；通常在调用 PaymentRequest() 构造方法之后触发

调用 CanMakePaymentEvent 事件的 respondWith() 方法允许 Service Worker 控制发出可以处理支付请求的信号；方法需要传入一个兑现一个布尔值的 Promise

处理支付

ServiceWorkerGlobalScope 中的 paymentrequest 事件在支付请求创建时触发，返回一个 PaymentRequestEvent 事件；通常在调用 PaymentRequest 接口的 show() 方法之后触发

调用 PaymentRequestEvent 事件的 openWindow() 方法；方法传入一个字符串参数，代表执行支付的网站 URL（需要同源）；方法返回一个兑现一个 WindowClient 实例的 Promise

调用 PaymentRequestEvent 事件的 respondWith() 方法返回自定义的支付请求执行结果；方法需要传入一个兑现一个对象的 Promise

管理支付

PaymentManager 接口用于管理支付相关内容，通过 ServiceWorkerRegistration 接口的 paymentManager 只读属性使用

PaymentManager 接口的 userHint 属性用于设置显示支付方式页面时展示的信息，即 hint

PaymentManager 接口的 enableDelegations() 方法设置委托支付应用收集而非交由浏览器收集的支付信息

方法接收一个字符串数组参数，代表设置的支付信息，各项需为 payerEmail payerName payerPhone shippingAddress 之一 （分别代表支付者的邮箱、姓名、手机号和居住地址）

方法返回一个 Promise

类型

1
2
3
4
5
6
7

AbortPaymentEvent

CanMakePaymentEvent

PaymentManager

PaymentRequestEvent

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Payment_Handler_API
• https://w3c.github.io/payment-handler/

Payment Request API 允许用户创建个人的付款方式以及选择偏好程度，并提供给网站及开发者使用

创建支付请求

调用 PaymentRequest() 构造方法创建一个 PaymentRequest 实例，代表实际的支付请求

方法需要传入一个对象数组参数，表示受网站支持的支付方式列表

该对象具有如下一些参数：

• supportedMethods 参数，接收一个字符串，表示支付方式的标识符，可以为一个指向支付平台的 URL 或一个标准化的支付方式标识符

• data 可选参数，接收一个可序列化的对象，表示支付方式的额外信息

注意 supportedMethods 参数的不同取值可能影响 data 参数的取值

当 supportedMethods 参数指定为 secure-payment-confirmation 时， data 参数需要为一个 SecurePaymentConfirmationRequest 结构的对象

方法需要传入一个对象参数，表示当前支付请求的信息

该对象具有如下一些参数：

• total 参数，接收一个对象，表示支付请求的总条目

  该对象具有如下一些参数：

  • label 参数，接收一个字符串，表示支付请求的条目名称

  • amount 参数，接收一个数值，表示支付请求的条目价格

  • pending 可选参数，接收一个布尔值，表示支付请求的条目名称；默认为 false

• id 可选参数，接收一个字符串，表示支付请求的 ID；若不指定浏览器将自动生成

• displayItems 可选参数，接收一个对象数组，表示支付请求的条目细节；默认为空数组；结构同 total 参数

• modifiers 可选参数，接收一个对象数组，表示支付请求针对特定支付方式的修改，如用于针对不同支付渠道调整支付总额

  该对象具有如下一些参数：

  • supportedMethods 参数，接收一个字符串，表示支付方式的标识符，可以为一个指向支付平台的 URL 或一个标准化的支付方式标识符

  • total 可选参数，接收一个对象，表示支付请求的总条目，结构同 total 可选参数

  • additionalDisplayItems 可选参数，接收一个对象数组，表示额外的支付请求的总条目，结构同 total 可选参数

  • data 可选参数，接收一个可序列化的对象，表示支付方式的额外信息

显示支付请求

调用 PaymentRequest 接口的 show() 方法显示已创建的支付请求

方法接收一个可选的对象参数，表示更新的支付请求参数，会覆盖原有的支付请求参数

该对象具有如下一些参数：

id 可选参数 displayItems 可选参数与 modifiers 可选参数，同 PaymentRequest 构造函数的第二参数的相应参数

paymentMethodErrors 可选参数

方法返回一个 Promise，其兑现一个 PaymentResponse 实例，表示支付请求的结果

取消支付请求

调用 PaymentRequest 接口的 abort() 方法提前终止支付请求，同时移除任何由其产生的界面

方法返回一个 Promise

支付请求可用性

调用 PaymentRequest 接口的 canMakePayment() 方法检测给定的支付请求是否受用户代理支持

方法返回一个 Promise，其兑现一个布尔值，表示给定支付请求能否正常完成

可以在调用 show() 方法前预先调用 canMakePayment() 方法，以检测对应方支付请求能否正常进行；或尽早使用类似参数新建实例，调用该实例的 canMakePayment() 方法检测是否受支持，再在必要时候新建另一个实例执行真正的支付请求

支付请求信息

可以通过 PaymentRequest 接口的 id 只读属性返回一个字符串，反映当前支付请求的 ID，由构造时传入的 id 参数决定

可以监听 PaymentRequest 接口的 paymentmethodchange 事件监听因为用户在界面中更改支付方式产生的变化，返回一个 PaymentMethodChangeEvent 事件

PaymentMethodChangeEvent 事件继承自 PaymentRequestUpdateEvent 事件

其 methodDetails 只读属性，返回一个对象或 null，表示当前支付请求细节

其 methodName 只读属性，返回一个字符串，表示当前的支付请求方式

PaymentRequestUpdateEvent 事件继承自 Event 事件

其 updateWith() 方法，接收一个对象参数或一个兑现一个对象的 Promise，表示更新的支付请求参数；结构同 show() 方法的参数

支付结果操作

PaymentResponse 接口的 complete() 方法通知用户代理支付请求已经完成

方法传入一个字符串可选参数，值为 fail success unknown 之一，表示支付请求的结果；默认为 unknown

方法传入一个对象可选参数，其 data 参数接收一个对象，表示额外的支付请求信息

方法返回一个 Promise

PaymentResponse 接口的 retry() 方法请求用户重新发起支付请求

方法传入一个对象可选参数，其 error 参数接收一个字符串，表示错误信息；其 paymentMethod 参数接收一个字符串，表示支付请求方法

方法返回一个 Promise

支付结果信息

PaymentResponse 接口表示支付结果

其 requestId 只读属性返回一个字符串，反映当前支付结果对应的支付请求的 ID，由构造时传入的 id 参数决定

其 methodName 只读属性返回一个字符串，反映当前支付结果方式

其 details 只读属性返回一个对象或 null，反映当前支付结果细节，通常由支付平台返回

其 toJSON() 方法返回一个序列化的对象，表示当前的支付结果

类型

1
2
3
4
5
6
7

PaymentRequest

PaymentResponse

PaymentMethodChangeEvent

PaymentRequestUpdateEvent

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Payment_Request_API
• https://w3c.github.io/payment-request/

Audio Output Devices API 允许开发者选择音频的输出设备（如麦克风，蓝牙设备等）

基本使用

通过调用 MediaDevices 接口的 selectAudioOutput() 方法让用户选择期望的音频输出设备

被选择的设备具有相应的权限，随后可以通过 MediaDevices 接口的 enumerateDevices() 方法选取，并通过 HTMLMediaElement 接口的 setSinkId() 方法将对应媒体元素的输出指定为用户期望的音频输出设备

当然，被选择的设备可能因为某些原因断开连接等，可以通过监听 MediaDevices 接口的 devicechange 事件在采取相应的措施

选取音频输出设备

MediaDevices 接口的 selectAudioOutput() 方法用于请求用户选取期望的音频输出设备，选择完成后可以通过 MediaDevices 接口的 enumerateDevices() 方法枚举到目标音频设备

方法接收一个可选的配置项参数，其 deviceId 参数指定一个设备 ID；若该设备已被授权，方法会直接兑现而不弹窗请求授权

方法返回一个兑现一个 MediaDeviceInfo 实例的 Promise，表示用户选取的设备的信息

若当前文档不具备粘性激活状态，抛出 InvalidStateError 异常

若拒绝授权使用设备，抛出 NotAllowedError 异常

若无法找到合法的音频输出设备，抛出 NotFoundError 异常

设置音频输出设备

HTMLMediaElement 接口的 setSinkId() 方法用于手动设置用于播放当前媒体元素的媒体输出设备

方法接收一个字符串，代表媒体输出设备的 ID

方法返回一个 Promise

若受权限策略限制或拒绝授权使用设备，抛出 NotAllowedError 异常

若传入参数与任一合法的音频输出设备无法匹配，抛出 NotFoundError 异常

若因为任何原因无法切换音频输出设备，抛出 AbortError 异常

HTMLMediaElement 接口的 sinkId 只读属性返回当前正在用于播放当前媒体元素的媒体输出设备的 ID，或空字符串，表示当前使用的是默认的媒体输出设备

权限策略

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

默认值是 self，即仅允许同源的浏览上下文使用该 API

权限 API

该 API 调用需要用户授予 speaker-selection 权限，可以调用 Permission.query() 方法检查用户是否已授予了该权限

类型

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

interface HTMLMediaElement {
  readonly sinkId: string
  setSinkId(DOMString: string): Promise<void>
}

interface MediaDevices {
  selectAudioOutput(options?: AudioOutputOptions): Promise<MediaDeviceInfo>
}

interface AudioOutputOptions {
  deviceId: string
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Audio_Output_Devices_API
• https://w3c.github.io/mediacapture-output/

MediaStream Image Capture API 用于管理和配置从照相设备中拍照或录像，同时支持获取一些设备参数，如图像大小、红眼模式以及闪光灯模式等

初始化

调用 ImageCapture() 构造方法创建一个图像捕获器

需要传入一个 MediaStreamTrack 参数，作为目标进行捕获的视频轨道

若传入的参数表示一个视频轨道，即其 kind 属性为 video，抛出 NotSupportedError 异常

可以调用 MediaDevices 接口的 getUserMedia() 方法从媒体设备获取到媒体流，随后调用 MediaStream 接口的 getVideoTracks() 方法获取到对应媒体流的视频轨道，并将此作为参数传入 ImageCapture() 构造方法

创建后，传入的 MediaStreamTrack 参数可以通过实例的 track 只读属性获取到其引用

拍照

调用 ImageCapture 接口的 takePhoto() 方法进行拍照

方法传入一个可选的表示照相配置项的对象参数，其属性如下：

• redEyeReduction 参数接收一个布尔值，表示相机是否启用了红眼模式

• imageHeight 参数接收一个数字，表示相机设备提供的照片高度

• imageWidth 参数接收一个数字，表示相机设备提供的照片宽度

• fillLightMode 参数接收一个字符串，值为 auto off flash 之一，表示相机启用的闪光模式

方法返回一个兑现一个 Blob 实例的 Promise

调用 ImageCapture 接口的 grabFrame() 方法进行截取快照

方法返回一个兑现一个 ImageBitmap 实例的 Promise

两方法在当前传输视频轨道的 readyState 不为 live，抛出 InvalidStateError 异常

两方法在因为其他未知原因无法完成操作，抛出 UnknownError 异常

参数及配置

调用 ImageCapture 接口的 getPhotoCapabilities() 方法获取允许配置的范围及设定，返回一个对象

• redEyeReduction 属性返回一个字符串，值为 never always controllable 之一，表示相机目前的红眼模式设定

• imageHeight 属性返回一个对象，包含 min max step 等属性，表示相机设备支持的照片高度范围

• imageWidth 属性返回一个对象，包含 min max step 等属性，表示相机设备支持的照片宽度范围

• fillLightMode 属性返回一个字符串数组，数组各项为 auto off flash 之一且不会重复，表示相机支持的闪光模式

调用 ImageCapture 接口的 getPhotoSettings() 方法获取目前的配置，返回一个对象

• redEyeReduction 属性返回一个布尔值，表示相机是否启用了红眼模式

• imageHeight 属性返回一个数字，表示相机设备提供的照片高度

• imageWidth 属性返回一个数字，表示相机设备提供的照片宽度

• fillLightMode 属性返回一个字符串，值为 auto off flash 之一，表示相机启用的闪光模式

两方法在当前传输视频轨道的 readyState 不为 live，抛出 InvalidStateError 异常

两方法在因为其他未知原因无法完成操作，抛出 OperationError 异常

相关参数

• whiteBalanceMode 参数，表示白平衡模式，值为 auto manual single-shot continuous 之一

• exposureMode 参数，表示曝光模式，值为 auto manual single-shot continuous 之一

• focusMode 参数，表示对焦模式，值为 auto manual single-shot continuous 之一

• pointsOfInterest 参数，表示兴趣点/测光中心（通过自动对焦、自动曝光、自动白平衡调整），值为一个 Point2D 数组

• exposureCompensation 参数，表示曝光补偿，值为一个数值

• exposureTime 参数，表示曝光时间，值为一个数值

• colorTemperature 参数，表示色温，值为一个数值

• iso 参数，表示 ISO 感光度，值为一个数值

• brightness 参数，表示亮度，值为一个数值

• contrast 参数，表示对比度，值为一个数值

• saturation 参数，表示饱和度，值为一个数值

• sharpness 参数，表示清晰度，值为一个数值

• focusDistance 参数，表示焦距，值为一个数值

• pan 参数，表示平移，值为一个数值

• tilt 参数，表示倾斜，值为一个数值

• zoom 参数，表示变焦比例，值为一个数值

• torch 参数，表示补光模式，值为一个布尔值

这些参数被拓展至以下一些结构：

• MediaTrackSupportedConstraints 结构
• MediaTrackConstraintSet 结构（从而拓展至 MediaTrackConstraints 结构）
• MediaTrackSettings 结构
• MediaTrackCapabilities（不含 pointsOfInterest 参数）结构

这些参数在图片捕获的媒体流中可用

类型

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

interface ImageCapture {
  takePhoto(photoSettings?: PhotoSettings): Promise<Blob>
  getPhotoCapabilities(): Promise<PhotoCapabilities>
  getPhotoSettings(): Promise<PhotoSettings>

  grabFrame(): Promise<ImageBitmap>

  readonly track: MediaStreamTrack
}

declare var ImageCapture: {
  prototype: ImageCapture
  new (videoTrack: MediaStreamTrack): ImageCapture
}

interface PhotoCapabilities {
  redEyeReduction: RedEyeReduction
  imageHeight: MediaSettingsRange
  imageWidth: MediaSettingsRange
  fillLightMode: FillLightMode[]
}

interface PhotoSettings {
  fillLightMode: FillLightMode
  imageHeight: number
  imageWidth: number
  redEyeReduction: boolean
}

interface MediaSettingsRange {
  max: number
  min: number
  step: number
}

type RedEyeReduction = "never" | "always" | "controllable"
type FillLightMode = "auto" | "off" | "flash"

interface MediaTrackSupportedConstraints {
  whiteBalanceMode?: boolean
  exposureMode?: boolean
  focusMode?: boolean
  pointsOfInterest?: boolean
  exposureCompensation?: boolean
  exposureTime?: boolean
  colorTemperature?: boolean
  iso?: boolean
  brightness?: boolean
  contrast?: boolean
  saturation?: boolean
  sharpness?: boolean
  focusDistance?: boolean
  pan?: boolean
  tilt?: boolean
  zoom?: boolean
  torch?: boolean
}

interface MediaTrackCapabilities {
  whiteBalanceMode?: string[]
  exposureMode?: string[]
  focusMode?: string[]
  exposureCompensation?: MediaSettingsRange
  exposureTime?: MediaSettingsRange
  colorTemperature?: MediaSettingsRange
  iso?: MediaSettingsRange
  brightness?: MediaSettingsRange
  contrast?: MediaSettingsRange
  saturation?: MediaSettingsRange
  sharpness?: MediaSettingsRange
  focusDistance?: MediaSettingsRange
  pan?: MediaSettingsRange
  tilt?: MediaSettingsRange
  zoom?: MediaSettingsRange
  torch?: boolean[]
}

interface MediaTrackConstraintSet {
  whiteBalanceMode?: ConstrainDOMString
  exposureMode?: ConstrainDOMString
  focusMode?: ConstrainDOMString
  pointsOfInterest?: ConstrainPoint2D
  exposureCompensation?: ConstrainDouble
  exposureTime?: ConstrainDouble
  colorTemperature?: ConstrainDouble
  iso?: ConstrainDouble
  brightness?: ConstrainDouble
  contrast?: ConstrainDouble
  saturation?: ConstrainDouble
  sharpness?: ConstrainDouble
  focusDistance?: ConstrainDouble
  pan?: ConstrainDouble | boolean
  tilt?: ConstrainDouble | boolean
  zoom?: ConstrainDouble | boolean
  torch?: ConstrainBoolean
}

interface MediaTrackSettings {
  whiteBalanceMode?: string
  exposureMode?: string
  focusMode?: string
  pointsOfInterest?: Point2D[]
  exposureCompensation?: number
  exposureTime?: number
  colorTemperature?: number
  iso?: number
  brightness?: number
  contrast?: number
  saturation?: number
  sharpness?: number
  focusDistance?: number
  pan?: number
  tilt?: number
  zoom?: number
  torch?: boolean
}

interface ConstrainPoint2DParameters {
  exact: Point2D[]
  ideal: Point2D[]
}

type ConstrainPoint2D = Point2D[] | ConstrainPoint2DParameters

type MeteringMode = "none" | "manual" | "single-shot" | "continuous"

interface Point2D {
  x?: number
  y?: number
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/MediaStream_Image_Capture_API
• https://w3c.github.io/mediacapture-image/

MediaStream Recording API 支持实现录制视频流的功能，录制的数据可以用于进一步分析、处理并保存至硬盘

该 API 主要通过 MediaRecorder 接口提供相关的功能

初始化录制

调用 MediaRecorder() 构造方法以创建一个录制器

需要传入一个 stream 参数，接收一个 MediaStream 实例，代表需要录制的媒体流

此外可以传入一个可选的配置项参数，具体属性如下：

• mimeType 参数接收一个字符串，需要为一个合法的 MIME 媒体类型，同时允许指定额外的编码格式，默认值为空字符串
• audioBitsPerSecond 参数接收一个正整数，指定录制音频的比特率
• videoBitsPerSecond 参数接收一个正整数，指定录制视频的比特率
• bitsPerSecond 参数接收一个正整数，指定默认比特率，若 audioBitsPerSecond 或 videoBitsPerSecond 未指定，对应的轨道采样率将会采用
• audioBitrateMode 参数，指定录制音频的比特率模式，值为 constant（恒定比特率）或 variable（变化比特率），默认为 variable
• videoKeyFrameIntervalDuration 参数接收一个时间戳，指定关键帧之间标称时间间隔，用户代理在生成关键帧时会综合考虑该参数与 videoKeyFrameIntervalCount 参数
• videoKeyFrameIntervalCount 参数接收一个正整数，指定关键帧之间帧数间隔，用户代理在生成关键帧时会综合考虑该参数与 videoKeyFrameIntervalDuration 参数

若传递的 mimeType 参数当前不受用户代理支持，抛出 NotSupportedError 异常

检测编码格式

MediaRecorder 接口的 isTypeSupported() 静态方法检测 MIME 媒体类型是否支持，即指定的 MIME 媒体类型以及编码格式能否使得用户代理成功进行录制

该方法接收一个字符串，代表需要检测的 MIME 媒体类型以及编码格式

该方法返回一个布尔值，指示该类型是否支持

开始录制

调用 MediaRecorder 接口的 start() 方法开始录制

默认会将捕获的数据放入到一个 Blob 实例中并在录制结束时通过 dataavailable 事件返回，或在调用 requestData() 方法时返回

可以可选的传入一个数字参数，指定单段记录的最长时间；此情况下会周期性地触发 dataavailable 事件，并返回在这个周期中录制的数据

若所在 MediaRecorder 实例的 state 属性不为 inactive，即已开始录制或已暂停录制时，抛出 InvalidStateError 异常

若媒体流的配置禁止录制，抛出 SecurityError 异常

若媒体流处于 inactive 状态；或 MediaRecorder 实例的 videoKeyFrameIntervalDuration 参数与 videoKeyFrameIntervalCount 参数均指定；或任一媒体流中的媒体轨道不支持使用当前配置进行录制，抛出 NotSupportedError 异常

MediaRecorder 接口的 start 事件在开始录制时触发，返回一个 Event 事件，如调用 MediaRecorder.start() 方法

暂停录制

调用 MediaRecorder 接口的 pause() 方法暂停录制

若所在 MediaRecorder 实例的 state 属性为 inactive，即未开始录制或已终止录制时，抛出 InvalidStateError 异常

调用 pause() 方法后，会先改变 state 属性，最后触发 pause 事件

MediaRecorder 接口的 pause 事件在结束录制时触发，返回一个 Event 事件，如调用 MediaRecorder.pause() 方法

恢复录制

调用 MediaRecorder 接口的 resume() 方法恢复录制

若所在 MediaRecorder 实例的 state 属性不为 inactive，即已开始录制或已暂停录制时，抛出 InvalidStateError 异常

调用 resume() 方法后，会先改变 state 属性，最后触发 resume 事件

MediaRecorder 接口的 resume 事件在结束录制时触发，返回一个 Event 事件，如调用 MediaRecorder.resume() 方法

结束录制

调用 MediaRecorder 接口的 stop() 方法终止录制

若所在 MediaRecorder 实例的 state 属性为 inactive，即未开始录制或已终止录制时，抛出 InvalidStateError 异常异常

调用 stop() 方法后，会先改变 state 属性，然后触发 dataavailable 事件，最后触发 stop 事件

MediaRecorder 接口的 stop 事件在结束录制时触发，返回一个 Event 事件，如调用 MediaRecorder.stop() 方法或录制中的媒体流结束；在触发此事件前触发一个 dataavailable 事件

接收数据

调用 MediaRecorder 接口的 requestData() 方法用于立即触发一个 dataavailable 事件

若所在 MediaRecorder 实例的 state 属性为 inactive，即未开始录制或已终止录制时，抛出 InvalidStateError 异常

MediaRecorder 接口的 dataavailable 事件在录制过程中产生数据时触发，返回一个 BlobEvent 事件，可能原因有：媒体流终止、调用 requestData() 方法或 stop() 方法、调用 start() 方法时传递了 timeslice 参数

BlobEvent 事件结构：

data 只读属性，表示与事件相关的二进制数据

timecode 只读属性，表示生成首个 chunk 和触发 BlobEvent 事件的时间差

异常处理

MediaRecorder 接口的 error 事件在录制过程中出现异常时触发

触发 error 事件后，会接着触发 dataavailable 事件，最后触发 stop 事件

若媒体流的配置发生变化导致无法继续录制，通过 error 事件抛出 SecurityError 异常

若媒体流增删媒体轨道，通过 error 事件抛出 InvalidModificationError 异常

若因为其他未知原因无法继续录制，通过 error 事件抛出 UnknownError 异常

录制状态

MediaRecorder 接口的 state 只读属性返回一个字符串，表示当前录制的状态，值可以为如下之一：

• inactive 表示录制事件未发生，如尚未开始录制或录制已终止
• recording 表示录制已经开始并且用户代理正在捕获数据
• paused 表示录制已经开始，但目前被暂停，但未终止或恢复

录制信息

MediaRecorder 接口的 stream 只读属性返回一个 MediaStream，表示正在录制的目标媒体流，即初始化时传入的 stream 参数

MediaRecorder 接口的 mimeType 只读属性返回一个字符串，指示正在录制的 MIME 类型，与初始化时传入的 mimeType 参数相关或由用户代理决定

MediaRecorder 接口的 audioBitsPerSecond 只读属性返回一个正整数，指示录制音频的比特率

MediaRecorder 接口的 videoBitsPerSecond 只读属性返回一个正整数，指示录制视频的比特率

MediaRecorder 接口的 audioBitrateMode 只读属性返回一个 constant 或 variable 之一，指示录制音频的比特率模式

类型

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

interface MediaRecorder extends EventTarget {
  readonly audioBitsPerSecond: number
  readonly mimeType: string
  readonly state: RecordingState
  readonly stream: MediaStream
  readonly videoBitsPerSecond: number
  pause(): void
  requestData(): void
  resume(): void
  start(timeslice?: number): void
  stop(): void
  ondataavailable: ((this: MediaRecorder, ev: BlobEvent) => any) | null
  onerror: ((this: MediaRecorder, ev: Event) => any) | null
  onpause: ((this: MediaRecorder, ev: Event) => any) | null
  onresume: ((this: MediaRecorder, ev: Event) => any) | null
  onstart: ((this: MediaRecorder, ev: Event) => any) | null
  onstop: ((this: MediaRecorder, ev: Event) => any) | null
}

declare var MediaRecorder: {
  prototype: MediaRecorder
  new(stream: MediaStream, options?: MediaRecorderOptions): MediaRecorder
  isTypeSupported(type: string): boolean
}

interface MediaRecorderOptions {
  audioBitsPerSecond?: number
  bitsPerSecond?: number
  mimeType?: string
  videoBitsPerSecond?: number
}

type RecordingState = "inactive" | "paused" | "recording"

interface BlobEvent extends Event {
  readonly data: Blob
  readonly timecode: DOMHighResTimeStamp
}

declare var BlobEvent: {
  prototype: BlobEvent
  new(type: string, eventInitDict: BlobEventInit): BlobEvent
}

interface BlobEventInit {
  data: Blob
  timecode?: DOMHighResTimeStamp
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/MediaStream_Recording_API
• https://w3c.github.io/mediacapture-record/

Save Data API 向网站提供用户是否倾向于节省流量使用的功能

使用

NetworkInformation 接口的 saveData 属性表示当前的用户是否倾向于节省流量使用

或通过 Save-Data 请求头获取，值为 on 或 off，该请求头是一个 Client Hint 头

类型

1
2
3

interface NetworkInformation {
  readonly saveData: boolean
}

链接

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

Screen Capture API 允许网站捕获屏幕共享媒体流，实现共享屏幕功能

使用

调用 MediaDevices 接口的 getDisplayMedia() 方法捕获屏幕共享媒体流

方法可以传递一个可选的配置项参数，参数结构如下：

• video 参数，同 MediaDevices 接口的 getUserMedia() 方法，默认为 true
• audio 参数，同 MediaDevices 接口的 getUserMedia() 方法，默认为 false
• controller 参数，接收一个 CaptureController 对象，可用于进一步操作捕获会话
• preferCurrentTab 参数，接收一个布尔值，表示是否将当前标签页设置为最突出的选择
• selfBrowserSurface 参数，接收 exclude 或 include 之一，指示是否应当允许捕获当前标签页，默认为 exclude
• systemAudio 参数，接收 exclude 或 include 之一，指示是否应当包含系统音频，默认为 include
• surfaceSwitching 参数，接收 exclude 或 include 之一，指示是否应当显示动态切换共享标签页的控件，默认为 exclude
• monitorTypeSurfaces 参数，接收 exclude 或 include 之一，指示是否应当包含显示界面，默认为 include

方法返回一个兑现一个 MediaStream 的 Promise

若 controller 参数已传递给一个屏幕媒体流，或当前未处于粘性激活状态、完全激活状态、完全聚焦状态之一，方法抛出 InvalidStateError 异常

若 video 参数被置为 false，audio 参数或 video 参数之一包含 advanced 选项或 min 属性或 exact 属性，方法抛出 TypeError 异常

若传递的限制屏幕的参数 max 的值小于可约束属性支持的下限，即此时无法捕获符合参数限制的屏幕媒体流，或应用参数限制失败，方法抛出 OverconstrainedError 异常

若无法获得对应的屏幕媒体流，方法抛出 NotFoundError 异常

若用户拒绝授权使用屏幕媒体流的权限，或用户代理网页限制使用屏幕共享，方法抛出 NotAllowedError 异常

若因为操作系统/程序/网页限制无法提供媒体流，抛出 NotReadableError 异常

若因为其他未知原因无法提供媒体流，抛出 AbortError 异常

CaptureController 简介：

可调用其构造方法创建一个 CaptureController 实例

可调用其 setFocusBehavior() 方法设置其聚焦策略，传入参数可以为 focus-captured-surface（转移焦点至捕获界面）或 no-focus-change（不转移焦点）

相关参数

• displaySurface 参数，指定显示界面的类型，值为 monitor window browser 之一
• logicalSurface 参数，指定是否为逻辑显示界面，返回一个布尔值
• cursor 参数，指定是否将光标包含在显示界面中，值为 never always motion 之一
• restrictOwnAudio 参数，控制是否尝试从移除由当前文档产生的音频，返回一个布尔值
• suppressLocalAudioPlayback 参数，控制是否将捕获的本地音频转发到本地扬声器设备，返回一个布尔值

这些参数被拓展至以下一些结构：

• MediaTrackSupportedConstraints 结构
• MediaTrackConstraintSet 结构（从而拓展至 MediaTrackConstraints 结构）
• MediaTrackSettings 结构
• MediaTrackCapabilities（不含 restrictOwnAudio 与 suppressLocalAudioPlayback 参数）结构

这些参数在屏幕共享的媒体流中可用

示例

权限策略

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

默认值是 self，即允许当前源的浏览上下文使用该 API

权限 API

该 API 每次调用都需要用户授予 display-capture 权限（即不会将该权限设置为 granted），可以调用 Permission.query() 方法检查用户是否拒绝授予该权限

类型

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

interface MediaDevices {
  getDisplayMedia(options?: DisplayMediaStreamOptions): Promise<MediaStream>
}

interface DisplayMediaStreamOptions {
  audio?: boolean | MediaTrackConstraints
  video?: boolean | MediaTrackConstraints
  controller: CaptureController
  selfBrowserSurface: SelfCapturePreferenceEnum
  systemAudio: SystemAudioPreferenceEnum
  surfaceSwitching: SurfaceSwitchingPreferenceEnum
  monitorTypeSurfaces: MonitorTypeSurfacesEnum
}

interface CaptureController extends EventTarget {
  setFocusBehavior(focusBehavior: CaptureStartFocusBehavior): void
}

declare var CaptureController: {
  prototype: CaptureController
  new(): CaptureController
}

type CaptureStartFocusBehavior = 'focus-capturing-application' | 'focus-captured-surface' | 'no-focus-change'
type SelfCapturePreferenceEnum = 'include' | 'exclude'
type SystemAudioPreferenceEnum = 'include' | 'exclude'
type SurfaceSwitchingPreferenceEnum = 'include' | 'exclude'
type MonitorTypeSurfacesEnum = 'include' | 'exclude'

interface MediaTrackSupportedConstraints {
  displaySurface?: boolean
  logicalSurface?: boolean
  cursor?: boolean
  restrictOwnAudio?: boolean
  suppressLocalAudioPlayback?: boolean
}

interface MediaTrackConstraintSet {
  displaySurface?: ConstrainDOMString
  logicalSurface?: ConstrainBoolean
  cursor?: ConstrainDOMString
  restrictOwnAudio?: ConstrainBoolean
  suppressLocalAudioPlayback?: ConstrainBoolean
}

interface MediaTrackSettings {
  displaySurface?: string
  logicalSurface?: boolean
  cursor?: string
  restrictOwnAudio?: boolean
  suppressLocalAudioPlayback?: boolean
}

interface MediaTrackCapabilities {
  displaySurface?: string
  logicalSurface?: boolean
  cursor?: string[]
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Screen_Capture_API
• https://w3c.github.io/mediacapture-screen-share/

Web Locks API 允许网页中的脚本异步地使用锁以控制任务的重复执行

该 API 可通过 Navigator 接口的 locks 属性或 WorkerNavigator 接口的 locks 属性使用

概念

该 API 中锁的概念与操作系统中的锁的概念类似

获取锁后，在执行任务时保持锁，完成任务后释放锁

在锁被保持时，同域内执行的其他脚本无法获取相同的锁，而是被放到执行队列中，在当前任务完成后并且锁被释放时，队列中的任务依次执行

因此多组执行脚本不会同时执行相同的任务，可用于数据同步等功能

另外，该 API 可能会出现死锁问题，因此需要谨慎避免复杂的嵌套锁，或设置合理的超时时间，亦注意合理地排序

该 API 支持的一些功能如，从异步任务中返回值，共享锁和独占锁模式，有条件获得锁，查询当前所有锁的状态，防止死锁的逃生舱

获取锁

LockManager 接口的 request() 方法用于请求获取锁

方法传入一个 name 参数，接受一个字符串，代表锁的标识符

方法可选地传入 options 参数，接收一个对象，代表锁的配置项

配置项的 mode 选项指定锁的模式，可以为 exclusive 或 shared 之一，默认为 exclusive

exclusive 表示对应的锁单个时间段内最多只能存在一个

shared 表示对应的锁单个时间段内允许存在多个

配置项的 ifAvailable 选项指定是否在锁已被授予其他任务时继续调用，需要是一个布尔值，默认为 false

配置项的 steal 选项指定是否强制释放已被授予其他任务的锁，需要是一个布尔值，默认为 false

配置项的 signal 选项用于终止锁的请求，需要是一个 AbortSignal

方法传入一个 callback 参数，接受一个回调方法，代表锁的对应任务，在锁被授予时调用

该回调方法调用时会传入一个 Lock 实例，代表当前锁

该回调方法允许返回一个 Promise，任务执行时锁会等待 Promise 兑现或拒绝之后再释放

方法返回一个 Promise，兑现的值取决于 callback 回调方法的返回值

若当前文档未处于活跃状态，InvalidStateError 异常会被抛出

若当前环境无法获取到锁管理器，SecurityError 异常会被抛出

若 name 参数以 - 开头，或 ifAvailable 选项和 steal 选项同时指定为 true，或 steal 选项被指定为 true 并且 mode 选项被指定为 shared，或 signal 选项被指定且 ifAvailable 选项和 steal 选项之一被指定为 true，NotSupportedError 异常会被抛出

若 signal 选项被指定且已被终止，AbortError 异常会被抛出

Lock 接口

其 name 参数指代请求锁时传递的锁标识符

其 mode 参数指代请求锁时传递的锁的模式

枚举锁

LockManager 接口的 query() 方法用于枚举当前域下所有的锁的状态

返回一个 Promise，兑现一个包含 held 属性和 pending 属性的对象，分别代表保持状态的锁和锁的进行中的请求；两属性均返回一个对象数组，包含类似 Lock 对象的 name 属性和 mode 属性以及 clientId 属性，该属性与 Client 接口的 id 属性相同

该方法生成的锁的状态只是在调用时间那一刻的快照，在调用之后实际状态可能随时发生改变

若当前文档未处于活跃状态，InvalidStateError 异常会被抛出

若当前环境无法获取到锁管理器，SecurityError 异常会被抛出

类型

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

interface NavigatorLocks {
  readonly locks: LockManager
}

interface Navigator extends NavigatorLocks {}

interface WorkerNavigator extends NavigatorLocks {}

interface Lock {
  readonly mode: LockMode
  readonly name: string
}

declare var Lock: {
  prototype: Lock
}

interface LockManager {
  query(): Promise<LockManagerSnapshot>
  request(name: string, callback: LockGrantedCallback): Promise<any>
  request(name: string, options: LockOptions, callback: LockGrantedCallback): Promise<any>
}

declare var LockManager: {
  prototype: LockManager
}

type LockMode = "exclusive" | "shared"

interface LockGrantedCallback {
  (lock: Lock | null): any
}

interface LockInfo {
  clientId?: string
  mode?: LockMode
  name?: string
}

interface LockManagerSnapshot {
  held?: LockInfo[]
  pending?: LockInfo[]
}

interface LockOptions {
  ifAvailable?: boolean
  mode?: LockMode
  signal?: AbortSignal
  steal?: boolean
}

链接

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

Media Capture from DOM Elements API 允许从 DOM 元素中捕获媒体流，包括 <canvas> <audio> <video> 等

从媒体元素捕获

通过调用 HTMLMediaElement 接口上的 captureStream() 方法获取到在媒体元素上展示的资源相应的媒体流

该方法返回一个 MediaStream 实例

从 <audio> 捕获时，返回的媒体流可能包含任意数量的音频轨道

从 <video> 捕获时，返回的媒体流可能包含单个视频轨道及任意数量的音频轨道

从画布元素捕获

通过调用 HTMLCanvasElement 接口上的 captureStream() 方法获取到在画布元素上展示的资源相应的媒体流

该方法传入一个可选的 frameRequestRate 参数，接收一个正数；若传入负数会抛出 NotSupportedError 异常

该方法返回一个 MediaStream 实例；特别的，返回的媒体流包含单个 CanvasCaptureMediaStreamTrack 视频轨道，提供了一些专属的属性及方法

默认在 <canvas> 元素内容更新时刷新媒体流数据，或根据 frameRequestRate 参数定时刷新媒体流数据

对于 <canvas> 元素中包含跨域的图片资源时，SecurityError 会被抛出

关于 CanvasCaptureMediaStreamTrack 接口

继承自 MediaStreamTrack 接口

其 canvas 只读属性返回与视频轨道绑定的 HTMLCanvasElement 元素

其 requestFrame()方法强制从 HTMLCanvasElement 元素捕获帧并发送到媒体流（可以利用该方法替代默认的策略，需在创建时传入参数 0）

类型

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

interface HTMLCanvasElement {
  captureStream(frameRequestRate?: number): MediaStream
}

interface HTMLMediaElement {
  captureStream(): MediaStream
}

interface CanvasCaptureMediaStreamTrack extends MediaStreamTrack {
  readonly canvas: HTMLCanvasElement
  requestFrame(): void
}

declare var CanvasCaptureMediaStreamTrack: {
  prototype: CanvasCaptureMediaStreamTrack
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Media_Capture_and_Streams_API
• https://w3c.github.io/mediacapture-fromelement/

Media Session API 允许开发者显示自定义的媒体元信息，自定义可用媒体平台控件及访问平台媒体密钥；用户代理可能会将这些信息提供给设备，便于设备媒体信息 UI 界面的展示

该 API 通过 MediaSession 接口提供相关功能，并藉由 Navigator 接口的 mediaSession 只读属性暴露 MediaSession 实例供开发者使用

媒体播放状态

MediaMetadata 接口的 playbackState 属性读取或设置媒体播放状态，值需为 none paused playing 之一

MediaMetadata 接口的 setPositionState() 方法用于设置媒体的播放状态信息，包括播放速度、播放位置和媒体总时间等

该方法传入一个 MediaPositionState 结构的对象参数

MediaPositionState 结构如下：

• duration 属性返回一个数字，代表媒体资源的播放持续时间；需要为正值，可以为正无穷以表示媒体播放没有尽头
• playbackRate 属性返回一个数字，代表媒体资源的播放速度；需要为正值
• position 属性返回一个数字，代表媒体资源的播放位置；需要不为零

媒体元信息

MediaMetadata 接口表示但个媒体元信息

该接口的 title 属性读取或设置其媒体资源的名称，为一个字符串

该接口的 artist 属性读取或设置其媒体资源的作者，团队，创建者等的名称，为一个字符串

该接口的 album 属性读取或设置其媒体资源的专辑或集合的名称，为一个字符串

该接口的 artwork 属性读取或设置其媒体资源的图片，为一个只读 MediaImage 结构的对象数组

MediaImage 结构如下：

• src 属性返回一个字符串，代表图片的 URL
• sizes 可选属性返回一个字符串，代表图片的尺寸，默认为空字符串，可用于避免用户代理不必要地缩放图像
• type 可选属性返回一个字符串，代表图片的 MIME 类型，默认为空字符串，可便于用户代理忽略其不支持的 MIME 类型图像

可调用 MediaMetadata() 构造方法创建一个媒体元信息

构造方法可传入一个可选的对象参数，对象各参数即 MediaMetadata 接口的各属性

MediaMetadata 接口的 metadata 属性读取或设置浏览器当前播放的媒体资源，用于浏览器向用户设备提供相应信息，默认为 null

媒体设备状态

MediaMetadata 接口的 setCameraActive() 方法用于设置摄像头状态信息

MediaMetadata 接口的 setMicrophoneActive() 方法用于设置麦克风状态信息

两方法均需传入一个布尔类型的参数，表示媒体设备的状态

监听设备媒体界面控件

MediaMetadata 接口的 setActionHandler() 方法用于设置设备媒体界面控件特定事件的触发方法

方法需要传入一个字符串参数，代表需要监听的事件类型

允许的事件类型如下：

• play 开始或恢复播放
• pause 暂停播放
• seekbackward 向后移动定位
• seekforward 向前移动定位
• previoustrack 回退到上一资源
• nexttrack 前进到下一资源
• skipad 跳过广告播放，可能因为设备或用户代理设置而失败
• stop 停止播放
• seekto 移动至指定定位
• togglemicrophone 切换麦克风状态
• togglecamera 切换摄像头状态
• hangup 结束通话
• previousslide 回退至上一幻灯片
• nextslide 前进至下一幻灯片
• togglecamera 切换摄像头状态

方法需要传入一个回调函数参数，该回调函数在特定事件触发时调用，并传入一个 MediaSessionActionDetails 结构的对象参数

MediaSessionActionDetails 结构如下：

• action 属性返回一个字符串，代表特定的事件
• fastSeek 属性返回一个布尔值，代表是否采用快速媒体定位，在 action 为 seekto 时可能提供
• seekOffset 属性返回一个数字，代表媒体定位的偏移量，在 action 为 seekforward 或 seekbackward 时可能提供
• seekTime 属性返回一个数字，代表媒体定位的目标时间，在 action 为 seekto 时提供

权限策略

该 API 调用受到 mediasession 权限策略的控制，可以通过 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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

interface Navigator {
  readonly mediaSession: MediaSession
}

interface MediaSession {
  metadata: MediaMetadata | null
  playbackState: MediaSessionPlaybackState
  setActionHandler(action: MediaSessionAction, handler: MediaSessionActionHandler | null): void
  setPositionState(state?: MediaPositionState): void
}

declare var MediaSession: {
  prototype: MediaSession
}

interface MediaPositionState {
  duration?: number
  playbackRate?: number
  position?: number
}

interface MediaMetadata {
  album: string
  artist: string
  artwork: ReadonlyArray<MediaImage>
  title: string
}

declare var MediaMetadata: {
  prototype: MediaMetadata
  new(init?: MediaMetadataInit): MediaMetadata
}

interface MediaMetadataInit {
  album?: string;
  artist?: string;
  artwork?: MediaImage[];
  title?: string;
}
interface MediaImage {
  sizes?: string
  src: string
  type?: string
}

type MediaSessionAction = "nexttrack" | "pause" | "play" | "previoustrack" | "seekbackward" | "seekforward" | "seekto" | "skipad" | "stop"
type MediaSessionPlaybackState = "none" | "paused" | "playing"

interface MediaSessionActionHandler {
  (details: MediaSessionActionDetails): void;
}

链接

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