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

属性

  • 全屏

    布尔值

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

  • 标签页的新捕获状态。

  • tabId

    number

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

CaptureOptions

属性

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 的工作方式类似。在标签页内进行网页导航时，捕获操作会持续进行，并会在标签页关闭或媒体流被扩展程序关闭时停止。

参数

  • 配置返回的媒体流。

  • callback

    函数

    callback 参数如下所示： 

    (stream: LocalMediaStream) => void

    • 在线播放

      LocalMediaStream

getCapturedTabs()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
)

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: CaptureInfo[]) => void

返回

  • Promise&lt;CaptureInfo[]&gt;

    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,
)

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

参数