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，則在具有相同安全來源的指定分頁中，任何影格的 getUserMedia() 呼叫都可以使用該 ID。
  • 如果未指定，從 Chrome 116 開始，ID 可用於與呼叫端位於相同算繪程序中，且具有相同安全來源的任何框架。也就是說，在 Service Worker 中取得的串流 ID 可用於螢幕外文件。

在 Chrome 116 之前，如果未指定 consumerTabId，串流 ID 會同時受限於呼叫端的安全來源、轉譯程序和轉譯框架。

瞭解詳情

如要進一步瞭解如何使用 chrome.tabCapture API，請參閱「錄製音訊和擷取螢幕畫面」。本文將示範如何使用 tabCapture 和相關 API 解決多個常見用途。

類型

CaptureInfo

屬性

  • 全螢幕

    布林值

    擷取分頁中的元素是否處於全螢幕模式。

  • 分頁的新擷取狀態。

  • tabId

    數字

    狀態變更的分頁 ID。

CaptureOptions

屬性

GetMediaStreamOptions

Chrome 71 以上版本

屬性

  • consumerTabId

    號碼 選填

    選用分頁 ID，該分頁稍後會叫用 getUserMedia() 來消耗串流。如未指定，則只有呼叫擴充功能可以使用產生的串流。只有在指定分頁中的影格，且安全來源與取用者分頁的來源相符時，才能使用串流。分頁的來源必須是安全來源，例如 HTTPS。

  • targetTabId

    號碼 選填

    要擷取內容的分頁 ID (選用)。如未指定，系統會選取目前啟用的分頁。只有擴充功能已取得 activeTab 權限的分頁，才能做為目標分頁。

MediaStreamConstraint

屬性

  • 必填

    物件

  • 選用

    object 選填

TabCaptureState

列舉

「pending」

「active」

「stopped」

「error」

方法

capture()

僅限前景 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

擷取目前使用中分頁的顯示區域。擴充功能叫用後，只能在目前有效的分頁上啟動擷取作業，與 activeTab 的運作方式類似。在分頁中瀏覽網頁時，系統會持續擷取畫面，直到分頁關閉或擴充功能關閉媒體串流為止。

參數

  • 設定傳回的媒體串流。

  • callback

    函式

    callback 參數如下： 

    (stream: LocalMediaStream) => void

    • 串流

      LocalMediaStream

getCapturedTabs()

chrome.tabCapture.getCapturedTabs(): Promise<CaptureInfo[]>

傳回已要求擷取或正在擷取的索引標籤清單，也就是 status != stopped 和 status != error。擴充功能可藉此通知使用者，現有索引標籤擷取作業會導致新的索引標籤擷取作業失敗 (或避免對相同索引標籤提出多餘要求)。

傳回

getMediaStreamId()

Chrome 71 以上版本 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
): Promise<string>

建立串流 ID，擷取目標分頁。與 chrome.tabCapture.capture() 方法類似，但會向取用者分頁傳回媒體串流 ID，而非媒體串流。

參數

傳回

  • Promise<string>

    Chrome 116 以上版本

事件

onStatusChanged

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

當分頁的擷取狀態變更時，就會觸發這個事件。擴充功能作者可藉此追蹤分頁的擷取狀態，確保網頁動作等 UI 元素保持同步。

參數