chrome.tabCapture

說明

使用 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

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

  • 分頁的新擷取狀態。

  • tabId

    號碼

    狀態已變更的分頁 ID。

CaptureOptions

屬性

GetMediaStreamOptions

Chrome 71 以上版本

屬性

  • consumerTabId

    數字 選填

    選用分頁 ID，此分頁稍後會叫用 getUserMedia() 以使用串流。如未指定，產生的串流只能由呼叫擴充功能使用。只有指定分頁的安全性來源與消耗器分頁來源相符，才能使用這個串流。分頁的來源必須是安全來源，例如 HTTPS。

  • targetTabId

    數字 選填

    要擷取的分頁標籤的選用分頁 ID。如未指定，系統將選取目前使用中的分頁。只有獲得 activeTab 權限的分頁才能設為目標分頁。

MediaStreamConstraint

屬性

  • 必要

    物件

  • 選填

    物件選用

TabCaptureState

列舉

方法

capture()

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

擷取目前使用中分頁的可見區域。只有在叫用擴充功能後，才能在目前使用中的分頁啟動擷取作業，與 activeTab 的運作方式類似。在分頁內瀏覽網頁時，擷取作業會保留下來，且當分頁關閉或擴充功能關閉媒體串流時，擷取作業就會停止。

參數

  • 設定傳回的媒體串流。

  • 回呼

    功能

    callback 參數如下所示： 

    (stream: LocalMediaStream)=>void

    • 串流

      LocalMediaStream

getCapturedTabs()

Promise 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
)

傳回已經要求擷取或正在擷取的分頁清單，亦即狀態 != 已停止和狀態 != 錯誤。這可讓擴充功能通知使用者現有的分頁擷取作業會導致無法成功擷取新分頁 (或是防止同一個分頁出現重複要求)。

參數

傳回

  • Promise<CaptureInfo[]>

    Chrome 116 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getMediaStreamId()

Promise Chrome 71 以上版本 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
)

建立串流 ID 以擷取目標分頁。與 chrome.tabCapture.capture() 方法類似，但會將媒體串流 ID (而不是媒體串流) 傳回至「用戶端」分頁。

參數

  • 選項

    GetMediaStreamOptions 選用

  • 回呼

    函式選用

    callback 參數如下所示： 

    (streamId: string)=>void

    • streamId

      字串

傳回

  • Promise<string>

    Chrome 116 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

活動

onStatusChanged

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

分頁擷取狀態變更時觸發事件。如此一來，擴充功能作者就能追蹤分頁擷取狀態，讓網頁動作等 UI 元素保持同步。

參數