---
title: MediaDevices.getDisplayMedia()
slug: Web/API/MediaDevices/getDisplayMedia
tags:
  - API
  - 会谈
  - 分享
  - 参考
  - 多媒体
  - 多媒体设备
  - 屏幕
  - 屏幕捕捉
  - 屏幕捕捉API
  - 捕捉
  - 方法
  - 显示
  - 获取显示多媒体
  - 视频
translation_of: Web/API/MediaDevices/getDisplayMedia
---
<div>{{DefaultAPISidebar("Screen Capture API")}}</div>

<p>这个 {{domxref("MediaDevices")}}  接口的 <code><strong>getDisplayMedia() 方法提示用户去选择和授权捕获展示的内容或部分内容（如一个窗口）在一个</strong></code>  {{domxref("MediaStream")}} 里. 然后，这个媒体流可以通过使用 <a href="/en-US/docs/Web/API/MediaStream_Recording_API">MediaStream Recording API</a> 被记录或者作为<a href="/en-US/docs/Web/API/WebRTC_API">WebRTC</a> 会话的一部分被传输。</p>

<p>去 <a href="/en-US/docs/Web/API/Screen_Capture_API/Using_Screen_Capture">Using the Screen Capture API</a> 查找更多详情和例子.</p>

<h2 id="语法">语法</h2>

<pre class="syntaxbox">var <em>promise</em> = navigator.mediaDevices.getDisplayMedia(<em>constraints</em>);
</pre>

<h3 id="参数">参数</h3>

<dl>
 <dt><code>constraints</code> {{optional_inline}}</dt>
 <dd>一个可选的{{domxref("MediaStreamConstraints")}}对象，它指定了返回的{{domxref("MediaStream")}}的要求。 因为<code>getDisplayMedia()</code>需要视频轨道，所以即使<code>constraints</code> 对象没有明确请求视频轨道，返回的流也会有一个。</dd>
</dl>

<h3 id="返回值">返回值</h3>

<p>一个被解析为 {{domxref("MediaStream")}} 的 {{jsxref("Promise")}}，其中包含一个视频轨道。视频轨道的内容来自用户选择的屏幕区域以及一个可选的音频轨道。</p>

<div class="blockIndicator note">
<p><strong>Note:</strong> 浏览器对音频的支持程度各不相同，既取决于是否支持，也取决于音频源. 点击 <a href="#浏览器兼容性">浏览器兼容性</a> 来查看各个浏览器的支持性.</p>
</div>

<h3 id="异常">异常</h3>

<p>来自返回的promise的拒绝是通过将{{domxref("DOMException")}}错误对象传递给promise的失败处理程序来进行的。可能的错误是：</p>

<dl>
 <dt><code>AbortError</code> ［中止错误］</dt>
 <dd>发生了与以下任何其他异常不匹配的错误或故障。</dd>
 <dt><code>InvalidStateError</code> ［拒绝错误］</dt>
 <dd>调用 <code>getDisplayMedia()</code> 的context中的 {{domxref("document")}} 不是完全激活的; 例如，也许它不是最前面的标签。</dd>
 <dt><code>NotAllowedError</code> ［拒绝错误］</dt>
 <dd>用户拒绝授予访问屏幕区域的权限，或者不允许当前浏览实例访问屏幕共享。</dd>
 <dt><code>NotFoundError</code> ［找不到错误］</dt>
 <dd>没有可用于捕获的屏幕视频源。</dd>
 <dt><code>NotReadableError</code> ［无法读取错误］</dt>
 <dd>用户选择了屏幕，窗口，标签或其他屏幕数据源，但发生了硬件或操作系统级别错误或锁定，从而预先占用了共享所选源。</dd>
 <dt><code>OverconstrainedError</code> ［转换错误］</dt>
 <dd>创建流后，由于无法生成兼容的流导致应用指定的 <code>constraints</code> 失效。</dd>
 <dt><code>TypeError</code> ［类型错误］</dt>
 <dd>指定的 <code>constraints</code> 包括调用 <code>getDisplayMedia()</code> 时不允许的<code>constraints</code>。 这些不受支持的<code>constraints</code>是 <code>advanced</code> 的，任何约束又有一个名为 <code>min</code> 或 <code>exact</code> 的成员。</dd>
</dl>

<h2 id="示例">示例</h2>

<p>在下面的示例中，我们创建了一个 <code>startCapture()</code> 方法，该方法在给定由 <code>displayMediaOptions</code> 参数指定的一组选项的情况下启动屏幕捕获。 选项以 {{domxref("MediaStreamConstraints")}}对象的形式指定，该对象指定首选流配置和从中捕获视频的显示表面</p>

<pre class="brush: js">async function startCapture(displayMediaOptions) {
  let captureStream = null;

  try {
    captureStream = await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
  } catch(err) {
    console.error("Error: " + err);
  }
  return captureStream;
}</pre>

<p>这里使用 {{jsxref("await")}} 来进行异步等待 <code>getDisplayMedia()</code>来进行 {{domxref("MediaStream")}}解析，其中包含指定选项所请求的显示内容。 之后，流被返回给调用者以供其使用，可能是使用 {{domxref("RTCPeerConnection.addTrack()")}}添加到WebRTC调用来从流中添加视频轨道。</p>

<h2 id="规范">规范</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">规范</th>
   <th scope="col">状态</th>
   <th scope="col">备注</th>
  </tr>
  <tr>
   <td>{{SpecName('Screen Capture', '#dom-mediadevices-getdisplaymedia', 'MediaDevices.getDisplayMedia()')}}</td>
   <td>{{Spec2('Screen Capture')}}</td>
   <td>初始定义</td>
  </tr>
 </tbody>
</table>

<h2 id="浏览器兼容性">浏览器兼容性</h2>

<div>
<p>{{Compat("api.MediaDevices.getDisplayMedia")}}</p>
</div>

<h2 id="参考">参考</h2>

<ul>
 <li><a href="/en-US/docs/Web/API/Screen_Capture_API">Screen Capture API</a></li>
 <li><a href="/en-US/docs/Web/API/Screen_Capture_API/Using_Screen_Capture">Using the Screen Capture API</a></li>
 <li><a href="/en-US/docs/Web/API/Media_Streams_API">Media Capture and Streams API</a></li>
 <li><a href="/en-US/docs/Web/API/WebRTC_API">WebRTC API</a></li>
 <li>{{domxref("MediaDevices.getUserMedia", "getUserMedia()")}}: Capturing media from a camera and/or microphone</li>
</ul>