说明
使用 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
标签页的新捕获状态。
-
tabId
number
状态已更改的标签页的 ID。
CaptureOptions
属性
-
市场
布尔值 选填
-
audioConstraints
-
视频
布尔值 选填
-
videoConstraints
GetMediaStreamOptions
属性
-
consumerTabId
数字可选
标签页的可选标签页 ID,此标签页稍后将调用
getUserMedia()
以使用数据流。如果未指定,则生成的流仅供调用扩展程序使用。只有指定标签页中的安全来源与消费者标签页的来源一致,才能使用数据流。标签页的源必须是安全源,例如 HTTPS。 -
targetTabId
数字可选
将要捕获的标签页的(可选)ID。如果未指定,则将选择当前的活动标签页。只有扩展程序被授予
activeTab
权限的标签页才能用作目标标签页。
MediaStreamConstraint
属性
-
必填
对象
-
可选
对象(可选)
TabCaptureState
枚举
"stopped"
方法
capture()
chrome.tabCapture.capture(
options: CaptureOptions,
callback: function,
)
捕获当前活动标签页的可见区域。只有在调用扩展程序后,才能在当前活跃的标签页上启动捕获,这与 activeTab 的工作方式类似。捕获在标签页中的各个网页导航期间都会保持不变,并会在标签页关闭或媒体流被扩展程序关闭时停止。
参数
-
配置返回的媒体流。
-
callback
功能
callback
参数如下所示:(stream: LocalMediaStream) => void
-
在线播放
LocalMediaStream
-
getCapturedTabs()
chrome.tabCapture.getCapturedTabs(
callback?: function,
)
返回已请求捕获或正在捕获的标签列表,即状态 != stop 和 status != 错误。这样一来,扩展程序便可以通知用户,目前存在的标签页截图会阻止新标签页截取成功(或者阻止针对同一标签页的重复请求)。
参数
-
callback
函数(可选)
callback
参数如下所示:(result: CaptureInfo[]) => void
-
结果
-
返回
-
Promise<CaptureInfo[]>
Chrome 116 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getMediaStreamId()
chrome.tabCapture.getMediaStreamId(
options?: GetMediaStreamOptions,
callback?: function,
)
创建数据流 ID 以捕获目标标签页。与 chrome.tabCapture.capture() 方法类似,但会将媒体流 ID(而不是媒体流)返回到使用方标签页。
参数
-
选项
-
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
-
资讯
-