chrome.tabCapture

refresh date: 2026-09-25 robots: noindex

Opis

Użyj interfejsu API chrome.tabCapture, aby korzystać ze strumieni multimediów na kartach.

Uprawnienia

tabCapture

Przegląd

Interfejs chrome.tabCapture API umożliwia dostęp do obiektu MediaStream zawierającego obraz i dźwięk z bieżącej karty. Można ją wywołać tylko po wywołaniu rozszerzenia przez użytkownika, np. przez kliknięcie przycisku polecenia rozszerzenia. Działa to podobnie jak uprawnienie activeTab.

Zachowywanie dźwięku systemowego

Gdy dla karty zostanie uzyskany obiekt MediaStream, dźwięk z tej karty nie będzie już odtwarzany użytkownikowi. Jest to podobne do działania funkcji getDisplayMedia(), gdy flaga suppressLocalAudioPlayback ma wartość true.

Aby kontynuować odtwarzanie dźwięku użytkownikowi, użyj tych opcji:

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

Spowoduje to utworzenie nowego obiektu AudioContext i połączenie dźwięku z obiektu MediaStream karty z domyślnym miejscem docelowym.

Identyfikatory strumieni

Wywołanie chrome.tabCapture.getMediaStreamId zwróci identyfikator strumienia. Aby później uzyskać dostęp do obiektu MediaStream za pomocą identyfikatora, użyj tego kodu:

navigator.mediaDevices.getUserMedia({
  audio: {
    mandatory: {
      chromeMediaSource: "tab",
      chromeMediaSourceId: id,
    },
  },
  video: {
    mandatory: {
      chromeMediaSource: "tab",
      chromeMediaSourceId: id,
    },
  },
});

Ograniczenia w zakresie użytkowania

Po wywołaniu metody getMediaStreamId() obowiązują ograniczenia dotyczące tego, gdzie można używać zwróconego identyfikatora strumienia:

  • Jeśli podano consumerTabId, identyfikator może być używany przez wywołanie getUserMedia() w dowolnej ramce na danej karcie, która ma to samo źródło zabezpieczeń.
  • Jeśli nie jest określony, od wersji Chrome 116 identyfikator może być używany w dowolnej ramce z tym samym źródłem zabezpieczeń w tym samym procesie renderowania co element wywołujący. Oznacza to, że identyfikator strumienia uzyskany w skrypcie service worker może być używany w dokumencie poza ekranem.

Przed wersją Chrome 116, gdy nie określono consumerTabId, identyfikator strumienia był ograniczony do źródła zabezpieczeń, procesu renderowania i ramki renderowania elementu wywołującego.

Więcej informacji

Więcej informacji o korzystaniu z interfejsu API chrome.tabCapture znajdziesz w artykule Nagrywanie dźwięku i przechwytywanie zawartości ekranu. Pokazuje, jak używać tabCapture i powiązanych interfejsów API do rozwiązywania wielu typowych problemów.

Typy

CaptureInfo

Właściwości

  • pełny ekran

    wartość logiczna

    Określa, czy element na przechwytywanej karcie jest w trybie pełnoekranowym.

  • Nowy stan przechwytywania karty.

  • tabId

    liczba

    Identyfikator karty, której stan uległ zmianie.

CaptureOptions

Właściwości

GetMediaStreamOptions

Chrome 71 lub nowsza wersja

Właściwości

  • consumerTabId

    number optional

    Opcjonalny identyfikator karty, która później wywoła getUserMedia(), aby wykorzystać strumień. Jeśli nie zostanie określony, wynikowy strumień może być używany tylko przez rozszerzenie wywołujące. Strumień może być używany tylko przez ramki na danej karcie, których źródło zabezpieczeń jest zgodne ze źródłem karty konsumenta. Źródło karty musi być bezpieczne, np. HTTPS.

  • targetTabId

    number optional

    Opcjonalny identyfikator karty, która zostanie przechwycona. Jeśli nie zostanie określona, zostanie wybrana aktualnie aktywna karta. Jako karty docelowej można używać tylko kart, dla których rozszerzenie ma uprawnienie activeTab.

MediaStreamConstraint

Właściwości

  • obowiązkowe

    obiekt

  • opcjonalnie

    object opcjonalny

TabCaptureState

Typ wyliczeniowy

"pending"

"active"

"stopped"

"error"

Metody

capture()

Tylko na pierwszym planie 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

Przechwytuje widoczny obszar aktywnej karty. Przechwytywanie można rozpocząć tylko na obecnie aktywnej karcie po wywołaniu rozszerzenia, podobnie jak w przypadku activeTab. Przechwytywanie jest utrzymywane podczas nawigacji na stronie na karcie i zatrzymuje się, gdy karta zostanie zamknięta lub strumień multimediów zostanie zamknięty przez rozszerzenie.

Parametry

  • Konfiguruje zwrócony strumień multimediów.

  • callback

    funkcja

    Parametr callback wygląda tak:

    (stream: LocalMediaStream) => void

    • strumień

      LocalMediaStream

getCapturedTabs()

Obietnica 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
): Promise<CaptureInfo[]>

Zwraca listę kart, które zażądały przechwytywania lub są przechwytywane, tzn. stan != zatrzymany i stan != błąd. Dzięki temu rozszerzenia mogą informować użytkownika, że istnieje już przechwytywanie karty, które uniemożliwiłoby nowe przechwytywanie karty (lub zapobiegać zbędnym żądaniom dotyczącym tej samej karty).

Parametry

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (result: CaptureInfo[]) => void

Zwroty

  • Promise<CaptureInfo[]>

    Chrome 116 lub nowsza wersja

    Zwraca obiekt Promise, który jest rozwiązywany za pomocą obiektu CaptureInfo[] w przypadku przechwyconych kart.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

getMediaStreamId()

Promise Chrome 71 lub nowsza wersja 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
): Promise<string>

Tworzy identyfikator strumienia, aby przechwycić docelową kartę. Podobnie jak metoda chrome.tabCapture.capture(), ale zwraca identyfikator strumienia multimediów, a nie strumień multimediów, do karty klienta.

Parametry

  • Opcje

    GetMediaStreamOptions opcjonalnie

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (streamId: string) => void

    • streamId

      tekst

Zwroty

  • Promise<string>

    Chrome 116 lub nowsza wersja

    Zwraca obiekt Promise, który rozwiązuje się z wynikiem. Jeśli się powiedzie, wynikiem będzie nieprzezroczysty ciąg znaków, który można przekazać do interfejsu API getUserMedia(), aby wygenerować strumień multimediów odpowiadający docelowej karcie. Utworzony streamId może zostać użyty tylko raz i wygaśnie po kilku sekundach, jeśli nie zostanie użyty.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

Wydarzenia

onStatusChanged

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

Zdarzenie wywoływane, gdy zmienia się stan przechwytywania karty. Dzięki temu autorzy rozszerzeń mogą śledzić stan przechwytywania kart, aby synchronizować elementy interfejsu, takie jak działania na stronie.

Parametry