说明
使用 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
属性
-
音频
布尔值(可选)
-
audioConstraints
-
视频
布尔值(可选)
-
videoConstraints
GetMediaStreamOptions
属性
-
consumerTabId
编号(选填)
标签页的可选标签页 ID,该标签页稍后将调用
getUserMedia()
来使用数据流。如果未指定,则生成的流只能由调用扩展程序使用。只有指定标签页中安全源与接收者标签页源一致的帧才能使用该串流。标签页的来源必须是安全来源,例如HTTPS。 -
targetTabId
编号(选填)
要捕获的标签页的可选标签页 ID。如果未指定,则会选择当前活动标签页。只有已向扩展程序授予
activeTab
权限的标签页才能用作目标标签页。
MediaStreamConstraint
属性
-
必填
对象
-
可选
对象(可选)
TabCaptureState
枚举
"待处理"
"有效"
"已停止"
"错误"
方法
capture()
chrome.tabCapture.capture(
options: CaptureOptions,
callback: function,
)
捕获当前活动标签页的可见区域。只有在扩展程序被调用后,才能开始捕获当前活动标签页,这与 activeTab 的工作方式类似。在标签页内进行网页导航时,捕获操作会持续进行,并会在标签页关闭或媒体流被扩展程序关闭时停止。
参数
-
配置返回的媒体流。
-
callback
函数
callback
参数如下所示:(stream: LocalMediaStream) => void
-
在线播放
LocalMediaStream
-
getCapturedTabs()
chrome.tabCapture.getCapturedTabs(
callback?: function,
)
返回已请求捕获或正在捕获的标签列表,即状态 != 已停止 而 状态 != 错误。这样一来,扩展程序便可告知用户现有的标签页截取操作会阻止截取新标签页的操作(或避免针对同一标签页的冗余请求)。
参数
-
callback
函数(可选)
callback
参数如下所示:(result: CaptureInfo[]) => void
-
结果
-
返回
-
Promise<CaptureInfo[]>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getMediaStreamId()
chrome.tabCapture.getMediaStreamId(
options?: GetMediaStreamOptions,
callback?: function,
)
创建数据流 ID 以捕获目标标签页。与 chrome.tabCapture.capture() 方法类似,但向使用方标签页返回媒体流 ID(而非媒体流)。
参数
-
选项
-
callback
函数(可选)
callback
参数如下所示:(streamId: string) => void
-
streamId
字符串
-
返回
-
承诺<字符串>
Chrome 116 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
事件
onStatusChanged
chrome.tabCapture.onStatusChanged.addListener(
callback: function,
)
标签页的拍摄状态发生变化时触发的事件。这样一来,扩展程序作者就可以跟踪标签页的捕获状态,以保持页面操作等界面元素保持同步。
参数
-
callback
函数
callback
参数如下所示:(info: CaptureInfo) => void
-
资讯
-