browser.tabCapture

说明

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

权限

tabCapture

概念和用法

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

保留系统音频

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

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

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

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

数据流 ID

调用 browser.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 可在与调用方具有相同安全源且位于同一渲染进程中的任何框架中使用。这意味着，在 Service Worker 中获取的视频流 ID 可以在屏幕外文档中使用。

在 Chrome 116 之前，如果未指定 consumerTabId，则数据流 ID 仅限于调用方的安全来源、渲染进程和渲染框架。

了解详情

如需详细了解如何使用 browser.tabCapture API，请参阅录音和屏幕截图。这演示了如何使用 tabCapture 和相关 API 来解决许多常见应用场景。

类型

CaptureInfo

属性

• 全屏

  布尔值

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

• 状态

  TabCaptureState

  标签页的新捕获状态。

• tabId

  数值

  状态发生变化的标签页的 ID。

CaptureOptions

属性

• 音频

  布尔值 （可选）

• audioConstraints

  MediaStreamConstraint 可选

• 视频

  布尔值 （可选）

• videoConstraints

  MediaStreamConstraint 可选

GetMediaStreamOptions

Chrome 71 及更高版本 browser.*（自 Chrome 148 起）

属性

• consumerTabId

  number 可选

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

• targetTabId

  number 可选

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

MediaStreamConstraint

属性

• 必填

  对象

• 可选

  对象（可选）

TabCaptureState

枚举

"pending"

"active"

"stopped"

"error"

方法

capture()

仅限前台

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

截取当前活动标签页的可视区域。只有在调用扩展程序后，才能在当前处于活动状态的标签页上开始捕获，这与 activeTab 的工作方式类似。在标签页内的网页导航过程中，系统会持续捕获，并在标签页关闭或扩展程序关闭媒体流时停止捕获。

参数

• 选项

  CaptureOptions

  配置返回的媒体流。

• callback

  函数

  callback 参数如下所示：

  (stream: LocalMediaStream) => void

  • 在线播放

    LocalMediaStream

getCapturedTabs()

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

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

返回

• Promise<CaptureInfo[]>

  Chrome 116 及更高版本 browser.*（自 Chrome 148 起）

  返回一个 Promise，该 Promise 会解析为所捕获标签页的 CaptureInfo[]。

getMediaStreamId()

Chrome 71 及更高版本 browser.*（自 Chrome 148 起）

browser.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
): Promise<string>

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

参数

• 选项

  GetMediaStreamOptions 可选

返回

• Promise<string>

  Chrome 116 及更高版本 browser.*（自 Chrome 148 起）

  返回一个 Promise，该 Promise 会解析结果。如果成功，结果将是一个不透明字符串，可传递给 getUserMedia() API 以生成与目标标签页对应的媒体流。创建的 streamId 只能使用一次，如果未使用，则会在几秒钟后过期。

事件

onStatusChanged

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

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

参数

• callback

  函数

  callback 参数如下所示：

  (info: CaptureInfo) => void

  • 信息

    CaptureInfo