此页面由 Cloud Translation API 翻译。

chrome.tabCapture

说明

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

权限

tabCapture

概念和用法

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

保留系统音频

当标签页获得 MediaStream 时，该标签页中的音频将不再向用户播放。这类似于当 suppressLocalAudioPlayback 标志设为 true 时 getDisplayMedia() 函数的行为。

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

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，则在具有相同安全来源的给定标签页中的任何框架中，都可以通过 getUserMedia() 调用使用该 ID。
如果未指定此值，从 Chrome 116 开始，该 ID 可用于与调用方位于同一渲染进程中且具有相同安全来源的任何框架。这意味着在服务工作线程中获取的流 ID 可用于离屏文档。

在 Chrome 116 之前，如果未指定 consumerTabId，则流 ID 会同时受调用方的安全来源、渲染进程和渲染框架的限制。

了解详情

如需详细了解如何使用 chrome.tabCapture API，请参阅音频录制和屏幕捕获。此示例演示了如何使用 tabCapture 及相关 API 来解决一些常见用例。

类型

CaptureInfo

属性

全屏

布尔值

被捕获的标签页中的元素是否处于全屏模式。
状态

TabCaptureState

相应标签页的新捕获状态。
tabId

数值

状态发生更改的标签页的 ID。

CaptureOptions

属性

音频

布尔值（可选）
audioConstraints

MediaStreamConstraint 可选
视频

布尔值（可选）
videoConstraints

MediaStreamConstraint 可选

GetMediaStreamOptions

Chrome 71 及更高版本

属性

consumerTabId

number 可选

稍后将调用 getUserMedia() 来使用该流的标签页的可选标签页 ID。如果未指定，则生成的流只能由调用扩展程序使用。该数据流只能由给定标签页中安全来源与消费者标签页来源相匹配的框架使用。标签页的来源必须是安全来源，例如 HTTPS。
targetTabId

number 可选

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

MediaStreamConstraint

属性

必填

对象
可选

对象（可选）

TabCaptureState

枚举

“待处理”

“有效”

“已停止”

“错误”

方法

capture()

仅限在前台运行时获取位置信息

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

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

参数

选项

CaptureOptions

配置返回的媒体流。
callback

函数

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

getCapturedTabs()

chrome.tabCapture.getCapturedTabs(): Promise<CaptureInfo[]>

返回已请求捕获或正在捕获的标签页的列表，即状态不为“已停止”且状态不为“错误”的标签页。这样一来，扩展程序就可以告知用户当前存在标签页捕获，这会阻止新的标签页捕获成功完成（或防止对同一标签页发出冗余请求）。

Promise<CaptureInfo[]>

Chrome 116 及更高版本

getMediaStreamId()