1. Web
  2. Web API
  3. MediaDevices
  4. getDisplayMedia()

MediaDevices: getDisplayMedia() 方法

可用性有限

此特性不是基线特性，因为它在一些最广泛使用的浏览器中不起作用。

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

MediaDevices 接口的 getDisplayMedia() 方法会提示用户选择一个显示器或显示器的一部分（例如一个窗口）并授予权限，将其捕获为一个 MediaStream。

生成的流随后可以使用 MediaStream 录制 API 进行录制，或者作为 WebRTC 会话的一部分进行传输。

有关更多详细信息和示例，请参阅 使用屏幕捕获 API。

语法

js
getDisplayMedia()
getDisplayMedia(options)

参数

options 可选

一个指定返回的 MediaStream 要求的对象。getDisplayMedia() 的选项与 MediaDevices.getUserMedia() 方法的 约束 的工作方式相同，尽管在这种情况下只能指定 audio 和 video。getDisplayMedia() 可能的选项属性列表如下：

video 可选

一个布尔值或 MediaTrackConstraints 实例；默认值为 true。如果省略此选项或将其设置为 true，则返回的 MediaStream 将包含一个视频轨道。由于 getDisplayMedia() 需要视频轨道，如果此选项设置为 false，则 Promise 将以 TypeError 拒绝。

audio 可选

一个布尔值或 MediaTrackConstraints 实例；默认值为 false。值为 true 表示返回的 MediaStream 将包含一个音频轨道，前提是音频受支持并且可用于用户选择的显示表面。

controller 可选

一个 CaptureController 对象实例，其中包含可用于进一步操作捕获会话的方法（如果包含）。

monitorTypeSurfaces 可选

一个枚举值，指定浏览器是否应在呈现给用户的屏幕捕获选项中，除了标签页和窗口选项之外，还提供整个屏幕的选项。此选项旨在防止用户因错误操作而在使用视频会议应用时泄露私人信息。可能的值为：

  • include: 提示浏览器应包含屏幕选项。
  • exclude: 提示应排除屏幕选项。

注意： 您不能同时设置 monitorTypeSurfaces: "exclude" 和 displaySurface: "monitor"，因为这两个设置是矛盾的。尝试这样做会导致 getDisplayMedia() 调用以 TypeError 失败。

preferCurrentTab 可选

一个布尔值；值为 true 会指示浏览器将当前标签页作为最突出的捕获源提供，即作为用户在“选择要共享的内容”选项中“此标签页”的单独选项。这很有用，因为许多应用类型通常只需要共享当前标签页。例如，一个幻灯片应用可能希望允许用户将包含演示文稿的当前标签页流式传输到虚拟会议。

selfBrowserSurface 可选

一个枚举值，指定浏览器是否应允许用户选择当前标签页进行捕获。这有助于避免视频会议应用无意中共享自身显示时出现的“无限镜厅”效应。可能的值为：

  • include: 提示浏览器应在提供的捕获选项中包含当前标签页。
  • exclude: 提示应从选项中排除当前标签页。
surfaceSwitching 可选

一个枚举值，指定浏览器是否应显示一个控件，允许用户在屏幕共享期间动态切换共享的标签页。这比用户每次想要切换共享标签页时都必须重新经历整个共享过程要方便得多。可能的值为：

  • include: 提示浏览器应包含该控件。
  • exclude: 提示不应显示该控件。
systemAudio 可选

一个枚举值，指定浏览器是否应在提供给用户的可能音频源中包含系统音频。可能的值为：

  • include: 提示浏览器应在选项列表中包含系统音频。
  • exclude: 提示应从显示的选项中排除系统音频。
windowAudio 可选

一个枚举值，提示浏览器在提供窗口共享选项时，应向用户呈现哪种音频共享选项。可能的值为：

  • exclude: 提示当选择窗口共享选项时，音频不应可共享。
  • window: 提示当选择窗口共享选项时，只应共享来自该窗口的音频。
  • system: 提示当选择窗口共享选项时，应共享所有系统音频。

注意： 对于这些选项中的大多数，规范并未强制规定默认值。对于未提及默认值的独立选项，请参阅 浏览器兼容性 部分以获取特定于浏览器的默认值。

注意： 有关这些选项如何工作的更多详细信息，请参阅文章 能力、约束和设置。

返回值

一个 Promise，它解析为一个 MediaStream，该流包含一个视频轨道（其内容来自用户选择的屏幕区域）以及一个可选的音频轨道。

注意： 浏览器对音频轨道的支持各不相同，包括媒体录制器是否支持它们，以及支持的音频源。有关每个浏览器的详细信息，请查看 兼容性表格。

异常

AbortError DOMException

如果在其他列出的异常之外发生错误或失败，则抛出此异常。

InvalidStateError DOMException

如果 getDisplayMedia() 的调用不是由由于 瞬时激活（如事件处理程序）而运行的代码引起的。或者浏览器上下文未完全激活或未获得焦点。或者 controller 选项已用于创建另一个 MediaStream。则抛出此异常。

NotAllowedError DOMException

如果用户拒绝访问屏幕区域的权限，或者当前浏览实例不允许访问屏幕共享（例如，通过 权限策略），则抛出此异常。

NotFoundError DOMException

如果没有可供捕获的屏幕视频源，则抛出此异常。

NotReadableError DOMException

如果用户选择了屏幕、窗口、标签页或其他屏幕数据源，但发生了硬件或操作系统级别的错误或锁定，导致无法共享选定的源，则抛出此异常。

OverconstrainedError DOMException

如果创建流后，应用任何指定的约束均因无法生成兼容的流而失败，则抛出此异常。

TypeError

如果指定的 options 包含在调用 getDisplayMedia() 时不允许的值（例如，video 属性设置为 false），或者任何指定的 MediaTrackConstraints 不允许，则抛出此异常。在 getDisplayMedia() 调用中使用的约束不允许 min 和 exact 值。

安全

由于 getDisplayMedia() 可能被用于不良用途，因此它可能带来重大的隐私和安全隐患。为此，规范详细说明了浏览器必须采取的措施才能完全支持 getDisplayMedia()。

  • 指定的选项不能用于限制用户可用的选择。相反，它们必须在用户选择源后应用，才能生成与选项匹配的输出。
  • 使用 getDisplayMedia() 的许可不能持久化以供重用。每次都必须提示用户授予权限。
  • 需要瞬时用户激活。用户必须与页面或 UI 元素进行交互才能使此功能正常工作。
  • 鼓励浏览器向用户发出关于共享包含浏览器的显示器或窗口的警告，并密切关注可能被捕获并展示给其他用户的内容。

示例

下面的示例创建了一个 startCapture() 方法，该方法根据 displayMediaOptions 参数指定的选项集启动屏幕捕获。

js
const displayMediaOptions = {
  video: {
    displaySurface: "browser",
  },
  audio: {
    suppressLocalAudioPlayback: false,
  },
  preferCurrentTab: false,
  selfBrowserSurface: "exclude",
  systemAudio: "include",
  surfaceSwitching: "include",
  monitorTypeSurfaces: "include",
};

async function startCapture(displayMediaOptions) {
  let captureStream;

  try {
    captureStream =
      await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
  } catch (err) {
    console.error(`Error: ${err}`);
  }
  return captureStream;
}

这使用了 await 来异步等待 getDisplayMedia() 解析为 MediaStream，该流包含根据指定选项请求的显示内容。然后将该流返回给调用者使用，或许可以使用 RTCPeerConnection.addTrack() 将流中的视频轨道添加到 WebRTC 调用中。

注意： 屏幕共享控件演示提供了一个完整的实现，允许您使用您选择的 getDisplayMedia() 约束和选项来创建屏幕捕获。

规范

规范
屏幕捕获
# dom-mediadevices-getdisplaymedia

浏览器兼容性

另见

帮助改进 MDN

了解如何贡献

此页面最后由 MDN 贡献者于 修改。

在 GitHub 上查看此页面 • 报告此内容的问题
© . Content available under a Creative Commons license.