browser.tabCapture

說明

使用 chrome.tabCapture API 與分頁媒體串流互動。

權限

tabCapture

概念和用途

您可以使用 browser.tabCapture API 存取包含目前分頁影片和音訊的 MediaStream。只有在使用者叫用擴充功能後 (例如點選擴充功能的動作按鈕)，才能呼叫這個方法。這與 "activeTab" 權限的行為類似。

保留系統音訊

當分頁取得 MediaStream 時，該分頁中的音訊就不會再向使用者播放。這與 suppressLocalAudioPlayback 旗標設為 true 時，getDisplayMedia() 函式的行為類似。

如要繼續向使用者播放音訊，請使用下列方法：

const output = new AudioContext();
const source = output.createMediaStreamSource(stream);
source.connect(output.destination);

這會建立新的 AudioContext，並將分頁 MediaStream 的音訊連線至預設目的地。

串流 ID

呼叫 browser.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 會受限於呼叫端的安全性來源、轉譯程序和轉譯框架。

瞭解詳情

如要進一步瞭解如何使用 browser.tabCapture API，請參閱「錄音和螢幕畫面擷取」。這項範例說明如何使用 tabCapture 和相關 API 解決多種常見用途。

類型

CaptureInfo

屬性

• 全螢幕

  布林值

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

• 狀態

  TabCaptureState

  分頁的新擷取狀態。

• tabId

  數字

  狀態變更的分頁 ID。

CaptureOptions

屬性

• 廣播

  布林值 選填

• audioConstraints

  MediaStreamConstraint 選用

• 影片

  布林值 選填

• videoConstraints

  MediaStreamConstraint 選用

GetMediaStreamOptions

Chrome 71 以上版本 瀏覽器* (自 Chrome 148 起)

屬性

• consumerTabId

  數字 選填

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

• targetTabId

  數字 選填

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

MediaStreamConstraint

屬性

• 必填

  物件

• 選填

  物件 選填

TabCaptureState

列舉

"pending"

"active"

「已停止」

"error"

方法

capture()

僅限前景

browser.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

擷取目前使用中分頁的可見區域。只有在叫用擴充功能後，才能在目前使用中的分頁上開始擷取，類似於 activeTab 的運作方式。在分頁內瀏覽網頁時，系統會持續擷取內容，直到分頁關閉或擴充功能關閉媒體串流為止。

參數

• 選項

  CaptureOptions

  設定傳回的媒體串流。

• callback

  函式

  callback 參數如下：

  (stream: LocalMediaStream) => void

  • 串流

    LocalMediaStream

getCapturedTabs()

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

傳回已要求擷取或正在擷取的分頁清單，即狀態不等於「已停止」且狀態不等於「錯誤」。這樣一來，擴充功能就能通知使用者，現有的分頁擷取功能會導致新的分頁擷取失敗 (或避免對同一個分頁提出多餘的要求)。

傳回

• Promise<CaptureInfo[]>

  Chrome 116 以上版本 Chrome 148 以上版本支援 browser.*

  傳回 Promise，其中包含所擷取分頁的 CaptureInfo[]。

getMediaStreamId()

Chrome 71 以上版本 瀏覽器* (自 Chrome 148 起)

browser.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
): Promise<string>

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

參數

• 選項

  GetMediaStreamOptions 選用

傳回

• Promise<string>

  Chrome 116 以上版本 Chrome 148 以上版本支援 browser.*

  傳回 Promise，並解析結果。如果成功，結果會是不透明字串，可傳遞至 getUserMedia() API，產生與目標分頁對應的媒體串流。建立的 streamId 只能使用一次，如果未使用，會在幾秒後過期。

事件

onStatusChanged

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

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

參數

• callback

  函式

  callback 參數如下：

  (info: CaptureInfo) => void

  • 資訊

    CaptureInfo