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() 呼叫即可在 具有相同安全性來源的分頁中
  • 如未指定，從 Chrome 116 開始，這個 ID 可以在任何 安全性來源與呼叫端相同。這意味著 服務工作處理程序可用於離線文件中。

在 Chrome 116 以下版本中，如果未指定 consumerTabId，串流 ID 會限定在 安全來源、轉譯程序及顯示呼叫端的框架。

瞭解詳情

如要進一步瞭解如何使用 chrome.tabCapture API，請參閱 音訊錄音和螢幕畫面擷取。這個範例說明如何使用 tabCapture 和相關 API 可用於解決許多常見用途。

類型

CaptureInfo

屬性

  • 全螢幕

    布林值

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

  • 分頁的新擷取狀態。

  • tabId

    數字

    狀態已變更的分頁編號。

CaptureOptions

屬性

GetMediaStreamOptions

Chrome 71 以上版本

屬性

  • consumerTabId

    編號 選填

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

  • targetTabId

    編號 選填

    待擷取分頁的選用分頁 ID。如未指定，將會選取目前使用中的分頁。只有已授予擴充功能 activeTab 權限的分頁，才能做為目標分頁使用。

MediaStreamConstraint

屬性

  • 必填

    物件

  • 選用

    物件 optional

TabCaptureState

列舉

「待處理」

"active"

"停止"

"錯誤"

方法

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 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getMediaStreamId()

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

建立串流 ID 來擷取目標分頁。與 chrome.tabCapture.capture() 方法類似，但會在「消費者」分頁中傳回媒體串流 ID，而非媒體串流。

參數

  • 選項

    GetMediaStreamOptions 選用

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (streamId: string) => void

    • streamId

      字串

傳回

  • 承諾<字串>

    Chrome 116 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

活動

onStatusChanged

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

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

參數