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。这意味着，从 Service Worker 中获取的数据流 ID 可用于屏幕外文档。

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

了解详情

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

类型

CaptureInfo

属性

• 全屏

  boolean

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

• status

  TabCaptureState

  标签页的新捕获状态。

• tabId

  number

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

CaptureOptions

属性

• 市场

  布尔值 选填

• audioConstraints

  MediaStreamConstraint 可选

• 视频

  布尔值 选填

• videoConstraints

  MediaStreamConstraint 可选

GetMediaStreamOptions

Chrome 71 及更高版本

属性

• consumerTabId

  数字可选

  标签页的可选标签页 ID，此标签页稍后将调用 getUserMedia() 以使用数据流。如果未指定，则生成的流仅供调用扩展程序使用。只有指定标签页中的安全来源与消费者标签页的来源一致，才能使用数据流。标签页的源必须是安全源，例如 HTTPS。

• targetTabId

  数字可选

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

MediaStreamConstraint

属性

• 必填

  对象

• 可选

  对象（可选）

TabCaptureState

枚举

"stopped"

方法

capture()

仅限前台

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

捕获当前活动标签页的可见区域。只有在调用扩展程序后，才能在当前活跃的标签页上启动捕获，这与 activeTab 的工作方式类似。捕获在标签页中的各个网页导航期间都会保持不变，并会在标签页关闭或媒体流被扩展程序关闭时停止。

参数

• 选项

  CaptureOptions

  配置返回的媒体流。

• callback

  功能

  callback 参数如下所示：

  (stream: LocalMediaStream)=>void

  • 在线播放

    LocalMediaStream

getCapturedTabs()

Promise

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

返回已请求捕获或正在捕获的标签列表，即状态 != stop 和 status != 错误。这样一来，扩展程序便可以通知用户，目前存在的标签页截图会阻止新标签页截取成功（或者阻止针对同一标签页的重复请求）。

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (result: CaptureInfo[])=>void

  • 结果

    CaptureInfo[]

返回

• Promise<CaptureInfo[]>

  Chrome 116 及更高版本

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

getMediaStreamId()

Promise Chrome 71 及更高版本

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

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

参数

• 选项

  GetMediaStreamOptions 可选

• callback

  函数（可选）

  callback 参数如下所示：

  (streamId: string)=>void

  • streamId

    string

返回

• Promise<string>

  Chrome 116 及更高版本

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

活动

onStatusChanged

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

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

参数

• callback

  功能

  callback 参数如下所示：

  (info: CaptureInfo)=>void

  • 资讯

    CaptureInfo