chrome.tabCapture

说明

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

权限

tabCapture

概览

借助 chrome.tabCapture API，您可以访问包含当前标签页的视频和 音频的 MediaStream。只有在用户调用扩展程序（例如 点击扩展程序的 操作按钮）后，才能调用此 API。这与 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 可在与调用方位于同一渲染进程中且具有相同安全来源的任何框架中使用。这意味着，在 Service Worker 中获取的数据流 ID 可在 离屏文档中使用。

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

了解详情

如需详细了解如何使用 chrome.tabCapture API，请参阅 录音和屏幕截图。此文档演示了如何使用 tabCapture 和相关 API 来解决一些常见用例。

类型

CaptureInfo

属性

  • fullscreen

    布尔值

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

  • 标签页的新捕获状态。

  • tabId

    数值

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

CaptureOptions

属性

GetMediaStreamOptions

Chrome 71 及更高版本

属性

  • consumerTabId

    数值 （可选）

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

  • targetTabId

    数值 （可选）

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

MediaStreamConstraint

属性

  • mandatory

    对象

  • optional

    对象（可选）

TabCaptureState

枚举

“pending”

“active”

“stopped”

“error”

方法

capture()

仅限在前台运行 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

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

参数

  • options

    CaptureOptions

    配置返回的媒体流。

  • callback

    函数

    callback 参数如下所示： 

    (stream: LocalMediaStream) => void

    • stream

      LocalMediaStream

getCapturedTabs()

Promise 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
): Promise<CaptureInfo[]>

返回已请求捕获或正在被捕获的标签页的列表，即 status != stopped 且 status != error。这样，扩展程序就可以告知用户存在现有标签页捕获，这会阻止新的标签页捕获成功（或防止对同一标签页发出冗余请求）。

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: CaptureInfo[]) => void

返回

  • Promise<CaptureInfo[]>

    Chrome 116 及更高版本

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

    Promise 仅适用于 Manifest V3 及更高版本，其他平台需要使用回调。

getMediaStreamId()

Promise Chrome 71+ 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
): Promise<string>

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

参数

  • options

    GetMediaStreamOptions （可选）

  • callback

    函数（可选）

    callback 参数如下所示： 

    (streamId: string) => void

    • streamId

      字符串

返回

  • Promise<string>

    Chrome 116 及更高版本

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

    Promise 仅适用于 Manifest V3 及更高版本，其他平台需要使用回调。

事件

onStatusChanged

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

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

参数