屏幕捕捉 API
========

屏幕捕获 API 对现有的媒体捕获和流 API 进行了补充，让用户选择一个屏幕或屏幕的一部分（如一个窗口）作为媒体流进行捕获。然后，该流可以被记录或通过网络与他人共享。

屏幕捕捉 API 的概念和用法
---------------

屏幕捕捉 API 使用起来相对简单。其唯一的方法是`MediaDevices.getDisplayMedia()`，它的任务是以捕获的形式要求用户选择一个屏幕或屏幕的一部分的`MediaStream`。

要开始从屏幕上捕捉视频，你需要在 `getDisplayMedia()` 的实例上调用 `Media` `navigator.mediaDevices`：


```js
captureStream =
  await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
```


The `Promise` returned by `getDisplayMedia()` resolves to a `MediaStream` which streams the captured media.

See the article Using the Screen Capture API for a more in-depth look at how to use the API to capture screen contents as a stream.

增加现有接口
------

屏幕捕捉 API 没有自己的任何接口，而是在现有的 `MediaDevices` 接口上添加了一个方法。

### MediaDevices 接口

`MediaDevices.getDisplayMedia()`

The `getDisplayMedia()` method is added to the `MediaDevices` interface. Similar to `getUserMedia()`, this method creates a promise that resolves with a `MediaStream` containing the display area selected by the user, in a format that matches the specified options.

Additions to existing dictionaries
----------------------------------

The Screen Capture API adds properties to the following dictionaries defined by other specifications.

### MediaTrackConstraints

`MediaTrackConstraints.cursor` (en-US)

A `ConstrainDOMString` (en-US) indicating whether or not the cursor should be included in the captured display surface's stream, and if it should always be visible or if it should only be visible while the mouse is in motion.

`MediaTrackConstraints.displaySurface` (en-US)

A `ConstrainDOMString` (en-US) indicating what type of display surface is to be captured. The value is one of `application`, `browser`, `monitor`, or `window`.

`MediaTrackConstraints.logicalSurface` (en-US)

Indicates whether or not the video in the stream represents a logical display surface (that is, one which may not be entirely visible onscreen, or may be completely offscreen). A value of `true` indicates a logical display surface is to be captured.

### MediaTrackSettings

`MediaTrackSettings.cursor` (en-US)

A string which indicates whether or not the display surface currently being captured includes the mouse cursor, and if so, whether it's only visible while the mouse is in motion or if it's always visible. The value is one of `always`, `motion`, or `never`.

`MediaTrackSettings.displaySurface` (en-US)

A string indicating what type of display surface is currently being captured. The value is one of `application`, `browser`, `monitor`, or `window`.

`MediaTrackSettings.logicalSurface` (en-US)

A Boolean value which is `true` if the video being captured doesn't directly correspond to a single onscreen display area.

### MediaTrackSupportedConstraints

`MediaTrackSupportedConstraints.cursor` (en-US)

A Boolean which is `true` if the user agent and device support the `MediaTrackConstraints.cursor` (en-US) constraint.

`MediaTrackSupportedConstraints.displaySurface` (en-US)

A Boolean which is `true` if the current environment supports the `MediaTrackConstraints.displaySurface` (en-US) constraint.

`MediaTrackSupportedConstraints.logicalSurface` (en-US)

A Boolean which is `true` if the current environment supports the constraint `MediaTrackConstraints.logicalSurface` (en-US).

Dictionaries
------------

The following dictionaries are defined by the Screen Capture API.

`CursorCaptureConstraint`

An enumerated string type used to provide the value for the `cursor` property for the settings and constraints. The possible values are `always`, `motion`, and `never`.

`DisplayCaptureSurfaceType`

An enumerated string type which is used to identify the kind of display surface to capture. This type is used for the `displaySurface` property in the constraints and settings objects, and has the possible values `application`, `browser`, `monitor`, and `window`.

Feature Policy validation
-------------------------

User agents that support Feature Policy (either using HTTP's `Permissions-Policy` header or the `<iframe>` attribute `allow`) can specify a desire to use the Screen Capture API using the policy control directive `display-capture`:


```html
<iframe allow="display-capture" src="/some-other-document.html"></iframe>
```


The default allow list is `self`, which lets the any content within the document use Screen Capture.

See Using Feature Policy for a more in-depth explanation of how Feature Policy is used.

规范
--

| Specification |
| --- |
| Screen Capture # dom-mediadevices-getdisplaymedia |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* Using the Screen Capture API (en-US)
* `MediaDevices.getDisplayMedia()`