此页面由 Cloud Translation API 翻译。

chrome.tabCapture

说明

使用 chrome.tabCapture API 与标签页媒体流进行交互。

权限

tabCapture

概念和用法

借助 chrome.tabCapture API，您可以访问包含视频和数据的 MediaStream。当前标签页的音频。只有在用户调用扩展程序后才能调用该方法，例如通过该扩展程序的操作按钮即可。这类似于 "activeTab" 权限。

保留系统音频

获取某个标签页的 MediaStream 后，系统将停止播放该标签页中的音频。这与 getDisplayMedia() 函数在以下情况的行为类似： suppressLocalAudioPlayback 标志设为 true。

如需继续向用户播放音频，请使用以下命令：

const output = new AudioContext();
const source = output.createMediaStreamSource(stream);
source.connect(output.destination);

这将创建一个新的 AudioContext，并将此标签页的 MediaStream 的音频连接到默认音频目标。

数据流 ID

调用 chrome.tabCapture.getMediaStreamId() 将返回数据流 ID。延后从该 ID 访问 MediaStream，请使用以下命令：

navigator.mediaDevices.getUserMedia({
  audio: {
    mandatory: {
      chromeMediaSource: "tab",
      chromeMediaSourceId: id,
    },
  },
  video: {
    mandatory: {
      chromeMediaSource: "tab",
      chromeMediaSourceId: id,
    },
  },
});

使用限制

调用 getMediaStreamId() 之后，会限制可以使用返回的数据流 ID：

如果指定了 consumerTabId，则该 ID 可由 getUserMedia() 调用在具有相同安全源的给定标签页。
如果未指定，从 Chrome 116 开始，此 ID 可用于任何具有与调用方位于同一渲染进程中的安全源。也就是说，获取的视频流 ID 可以在屏幕外文档中使用。

在 Chrome 116 之前，未指定 consumerTabId 时，视频流 ID 就仅限于调用方的安全来源、渲染进程和渲染帧。

了解详情

如需详细了解如何使用 chrome.tabCapture API，请参阅录音和屏幕截图。这展示了如何使用 tabCapture 和相关 API 来解决许多常见用例的问题。

类型

CaptureInfo

属性

全屏

布尔值

正在截取的标签页中的元素是否处于全屏模式。
状态

TabCaptureState

标签页的新捕获状态。
tabId

number

状态已更改的标签页的 ID。

CaptureOptions

属性

音频

布尔值（可选）
audioConstraints

MediaStreamConstraint 可选
视频

布尔值（可选）
videoConstraints

MediaStreamConstraint 可选

GetMediaStreamOptions

Chrome 71 及更高版本

属性

consumerTabId

编号（选填）

标签页的可选标签页 ID，该标签页稍后将调用 getUserMedia() 来使用数据流。如果未指定，则生成的流只能由调用扩展程序使用。只有指定标签页中安全源与接收者标签页源一致的帧才能使用该串流。标签页的来源必须是安全来源，例如HTTPS。
targetTabId

编号（选填）

要捕获的标签页的可选标签页 ID。如果未指定，则会选择当前活动标签页。只有已向扩展程序授予 activeTab 权限的标签页才能用作目标标签页。

MediaStreamConstraint

属性

必填

对象
可选

对象（可选）

TabCaptureState

枚举

"待处理"

"有效"

"已停止"

"错误"

方法

capture()

<ph type="x-smartling-placeholder"></ph> 仅限前台

chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
)

捕获当前活动标签页的可见区域。只有在扩展程序被调用后，才能开始捕获当前活动标签页，这与 activeTab 的工作方式类似。在标签页内进行网页导航时，捕获操作会持续进行，并会在标签页关闭或媒体流被扩展程序关闭时停止。

参数

选项

CaptureOptions

配置返回的媒体流。
callback

函数

callback 参数如下所示：
```
(stream: LocalMediaStream) => void
```
- 在线播放
  
  LocalMediaStream

getCapturedTabs()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.tabCapture.getCapturedTabs(
  callback?: function,
)

返回已请求捕获或正在捕获的标签列表，即状态 != 已停止而状态 != 错误。这样一来，扩展程序便可告知用户现有的标签页截取操作会阻止截取新标签页的操作（或避免针对同一标签页的冗余请求）。

参数

callback

函数（可选）

callback 参数如下所示：
```
(result: CaptureInfo[]) => void
```
- 结果
  
  CaptureInfo[]

Promise<CaptureInfo[]>

Chrome 116 及更高版本

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getMediaStreamId()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 71 及更高版本

chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
)

创建数据流 ID 以捕获目标标签页。与 chrome.tabCapture.capture() 方法类似，但向使用方标签页返回媒体流 ID（而非媒体流）。

参数

选项

GetMediaStreamOptions 可选
callback

函数（可选）

callback 参数如下所示：
```
(streamId: string) => void
```
- streamId
  
  字符串

承诺<字符串>

Chrome 116 及更高版本

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

事件

onStatusChanged

chrome.tabCapture.onStatusChanged.addListener(
  callback: function,
)

标签页的拍摄状态发生变化时触发的事件。这样一来，扩展程序作者就可以跟踪标签页的捕获状态，以保持页面操作等界面元素保持同步。

参数

callback

函数

callback 参数如下所示：
```
(info: CaptureInfo) => void
```
- 资讯
  
  CaptureInfo