說明
使用 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()
呼叫可在具有相同安全性來源的指定分頁的任何頁框中使用。 - 如未指定,從 Chrome 116 開始,您可以在任何與呼叫端相同安全性來源的頁框中使用這個 ID。這表示從 Service Worker 取得的串流 ID 可用於畫面外文件。
在 Chrome 116 之前,如未指定 consumerTabId
,則串流 ID 僅限於呼叫端的安全性來源、轉譯程序和呼叫框。
瞭解詳情
如要進一步瞭解如何使用 chrome.tabCapture
API,請參閱「音訊錄音和螢幕畫面擷取」。本示範將說明如何使用 tabCapture
和相關 API 解決各種常見用途。
類型
CaptureInfo
屬性
-
全螢幕
boolean
擷取的分頁中的元素是否使用全螢幕模式。
-
status
分頁的新擷取狀態。
-
tabId
號碼
狀態已變更的分頁 ID。
CaptureOptions
屬性
-
音訊內容
布林值 (選用)
-
audioConstraints
-
影片
布林值 (選用)
-
videoConstraints
GetMediaStreamOptions
屬性
-
consumerTabId
數字 選填
選用分頁 ID,此分頁稍後會叫用
getUserMedia()
以使用串流。如未指定,產生的串流只能由呼叫擴充功能使用。只有指定分頁的安全性來源與消耗器分頁來源相符,才能使用這個串流。分頁的來源必須是安全來源,例如 HTTPS。 -
targetTabId
數字 選填
要擷取的分頁標籤的選用分頁 ID。如未指定,系統將選取目前使用中的分頁。只有獲得
activeTab
權限的分頁才能設為目標分頁。
MediaStreamConstraint
屬性
-
必要
物件
-
選填
物件選用
TabCaptureState
列舉
方法
capture()
chrome.tabCapture.capture(
options: CaptureOptions,
callback: function,
)
擷取目前使用中分頁的可見區域。只有在叫用擴充功能後,才能在目前使用中的分頁啟動擷取作業,與 activeTab 的運作方式類似。在分頁內瀏覽網頁時,擷取作業會保留下來,且當分頁關閉或擴充功能關閉媒體串流時,擷取作業就會停止。
參數
-
設定傳回的媒體串流。
-
回呼
功能
callback
參數如下所示:(stream: LocalMediaStream) => void
-
串流
LocalMediaStream
-
getCapturedTabs()
chrome.tabCapture.getCapturedTabs(
callback?: function,
)
傳回已經要求擷取或正在擷取的分頁清單,亦即狀態 != 已停止和狀態 != 錯誤。這可讓擴充功能通知使用者現有的分頁擷取作業會導致無法成功擷取新分頁 (或是防止同一個分頁出現重複要求)。
參數
-
回呼
函式選用
callback
參數如下所示:(result: CaptureInfo[]) => void
-
結果
-
傳回
-
Promise<CaptureInfo[]>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getMediaStreamId()
chrome.tabCapture.getMediaStreamId(
options?: GetMediaStreamOptions,
callback?: function,
)
建立串流 ID 以擷取目標分頁。與 chrome.tabCapture.capture() 方法類似,但會將媒體串流 ID (而不是媒體串流) 傳回至「用戶端」分頁。
參數
-
選項
-
回呼
函式選用
callback
參數如下所示:(streamId: string) => void
-
streamId
字串
-
傳回
-
Promise<string>
Chrome 116 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
活動
onStatusChanged
chrome.tabCapture.onStatusChanged.addListener(
callback: function,
)
分頁擷取狀態變更時觸發事件。如此一來,擴充功能作者就能追蹤分頁擷取狀態,讓網頁動作等 UI 元素保持同步。
參數
-
回呼
功能
callback
參數如下所示:(info: CaptureInfo) => void
-
資訊
-