MediaDevices: getUserMedia() 方法

Baseline 已广泛支持

此功能已成熟，可跨多种设备和浏览器版本使用。自 2017 年 9 月以来，它已在浏览器中提供。

安全上下文： 此功能仅在安全上下文（HTTPS）中可用，且支持此功能的浏览器数量有限。

getUserMedia() 方法是 MediaDevices 接口的一个方法，它会提示用户授予权限以使用媒体输入设备，从而生成一个包含所需媒体类型轨道的 MediaStream。

该媒体流可以包含，例如，一个视频轨道（由硬件或虚拟视频源生成，如摄像头、视频录制设备、屏幕共享服务等），一个音频轨道（同样，由物理或虚拟音频源生成，如麦克风、A/D 转换器等），以及可能其他类型的轨道。

它返回一个 Promise，该 Promise 在成功时解析为一个 MediaStream 对象。如果用户拒绝权限，或者没有可用的匹配媒体，则 Promise 会分别以 NotAllowedError 或 NotFoundError DOMException 拒绝。

注意： 返回的 Promise 既可能不解析也不拒绝，因为用户不一定需要做出选择，并且可能会忽略请求。

语法

getUserMedia(constraints)

参数

约束

一个对象，用于指定请求的媒体类型，以及每种类型的任何要求。

constraints 参数是一个包含 video 和 audio 两个成员的对象，用于描述请求的媒体类型。必须指定其中一个或两个。如果浏览器找不到所有符合给定约束条件的指定类型的媒体轨道，则返回的 Promise 会以 NotFoundError DOMException 拒绝。

对于 video 和 audio，其值可以是布尔值或对象。默认值为 false。

如果为媒体类型指定 true，则生成的媒体流必须包含该类型的轨道。如果由于任何原因无法包含，返回的 Promise 将被拒绝。
如果为媒体类型指定 false，则生成的媒体流不得包含该类型的轨道，否则返回的 Promise 将被拒绝。因为 video 和 audio 都默认为 false，所以如果 constraints 对象不包含任何属性或根本不存在，返回的 Promise 将始终被拒绝。
如果为媒体类型指定了一个对象，该对象将被读取为 MediaTrackConstraints 字典。

返回值

一个 Promise，当成功获取到请求的媒体时，其完成处理程序会接收一个 MediaStream 对象。

异常

AbortError DOMException: 尽管用户和操作系统都已授予对硬件设备的访问权限，并且没有发生导致 NotReadableError DOMException 的硬件问题，但如果发生阻止设备使用的问题，则抛出此异常。
InvalidStateError DOMException: 如果当前文档未完全激活，则抛出此异常。
NotAllowedError DOMException: 如果一个或多个请求的源设备当前无法使用，则抛出此异常。这会在浏览上下文不安全（即页面使用 HTTP 而非 HTTPS 加载）时发生。如果用户指定当前浏览实例不允许访问设备、用户已拒绝当前会话的访问权限，或者用户已全局拒绝所有用户媒体设备的访问权限，也会发生这种情况。在支持使用 Permissions Policy 管理媒体权限的浏览器上，如果 Permissions Policy 未配置为允许访问输入源，则返回此错误。

注意： 规范的旧版本使用 SecurityError 代替此错误；SecurityError 已具有新含义。
NotFoundError DOMException: 如果未找到满足给定约束条件的指定类型的媒体轨道，则抛出此异常。
NotReadableError DOMException: 如果用户已授予使用匹配设备的权限，但操作系统、浏览器或网页级别发生硬件错误，阻止了对设备的访问，则抛出此异常。
OverconstrainedError DOMException: 如果指定的约束条件导致没有符合请求标准的候选设备，则抛出此异常。该错误是一个 OverconstrainedError 类型的对象，并具有一个 constraint 属性，其字符串值是无法满足的约束条件的名称，以及一个 message 属性，其中包含解释问题的可读字符串。

注意： 由于此错误甚至可能在用户尚未授予使用底层设备的权限时发生，因此它可能被用作指纹识别表面。
SecurityError DOMException: 如果调用 getUserMedia() 的 Document 上禁用了用户媒体支持，则抛出此异常。启用和禁用用户媒体支持的机制由各个用户代理自行决定。
TypeError: 如果指定的约束列表为空，或所有约束都设置为 false，则抛出此异常。如果在不安全的环境中尝试调用 getUserMedia() 也可能发生这种情况，因为在不安全的环境中 navigator.mediaDevices 是 undefined。

隐私和安全

作为一项可能涉及重大隐私问题的 API，getUserMedia() 的规范规定了浏览器必须满足的广泛隐私和安全要求。

getUserMedia() 是一项强大的功能，只能在安全上下文中使用；在不安全上下文中，navigator.mediaDevices 是 undefined，从而阻止访问 getUserMedia()。简而言之，安全上下文是使用 HTTPS 或 file:/// URL 方案加载的页面，或从 localhost 加载的页面。