chrome.tabCapture

refresh date: 2026-09-25 robots: noindex

Descrizione

Utilizza l'API chrome.tabCapture per interagire con gli stream multimediali delle schede.

Autorizzazioni

tabCapture

Panoramica

L'API chrome.tabCapture ti consente di accedere a un MediaStream contenente video e audio della scheda corrente. Può essere chiamato solo dopo che l'utente richiama un'estensione, ad esempio facendo clic sul pulsante di azione dell'estensione. Questo comportamento è simile a quello dell'autorizzazione activeTab.

Preservare l'audio di sistema

Quando viene ottenuto un MediaStream per una scheda, l'audio di quella scheda non verrà più riprodotto per l'utente. Questo comportamento è simile a quello della funzione getDisplayMedia() quando il flag suppressLocalAudioPlayback è impostato su true.

Per continuare a riprodurre l'audio per l'utente, utilizza quanto segue:

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

In questo modo viene creato un nuovo AudioContext e l'audio del MediaStream della scheda viene collegato alla destinazione predefinita.

ID stream

La chiamata a chrome.tabCapture.getMediaStreamId restituirà un ID stream. Per accedere in un secondo momento a un MediaStream dall'ID, utilizza quanto segue:

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

Limitazioni all'utilizzo

Dopo aver chiamato getMediaStreamId(), esistono limitazioni su dove è possibile utilizzare l'ID stream restituito:

  • Se viene specificato consumerTabId, l'ID può essere utilizzato da una chiamata getUserMedia() in qualsiasi frame della scheda specificata che ha la stessa origine di sicurezza.
  • Se non viene specificato, a partire da Chrome 116 l'ID può essere utilizzato in qualsiasi frame con la stessa origine di sicurezza nello stesso processo di rendering del chiamante. Ciò significa che un ID stream ottenuto in un service worker può essere utilizzato in un documento fuori schermo.

Prima di Chrome 116, quando non veniva specificato un consumerTabId, l'ID stream era limitato all'origine di sicurezza, al processo di rendering e al frame di rendering del chiamante.

Scopri di più

Per scoprire di più su come utilizzare l'API chrome.tabCapture, consulta Registrazione audio e acquisizione schermo. In questo modo viene mostrato come utilizzare tabCapture e le API correlate per risolvere una serie di casi d'uso comuni.

Tipi

CaptureInfo

Proprietà

  • schermo intero

    booleano

    Indica se un elemento nella scheda acquisita è in modalità a schermo intero.

  • Il nuovo stato di acquisizione della scheda.

  • tabId

    numero

    L'ID della scheda il cui stato è cambiato.

CaptureOptions

Proprietà

GetMediaStreamOptions

Chrome 71 e versioni successive

Proprietà

  • consumerTabId

    number optional

    ID scheda facoltativo della scheda che in seguito richiamerà getUserMedia() per utilizzare lo stream. Se non specificato, lo stream risultante può essere utilizzato solo dall'estensione chiamante. Lo stream può essere utilizzato solo dai frame nella scheda specificata la cui origine di sicurezza corrisponde all'origine della scheda consumer. L'origine della scheda deve essere un'origine sicura, ad esempio HTTPS.

  • targetTabId

    number optional

    ID facoltativo della scheda che verrà acquisita. Se non specificata, verrà selezionata la scheda attualmente attiva. Solo le schede per le quali all'estensione è stata concessa l'autorizzazione activeTab possono essere utilizzate come scheda di destinazione.

MediaStreamConstraint

Proprietà

  • obbligatorio

    oggetto

  • facoltativo

    object facoltativo

TabCaptureState

Enum

"pending"

"active"

"stopped"

"error"

Metodi

capture()

Solo in primo piano 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

Acquisisce l'area visibile della scheda attualmente attiva. L'acquisizione può essere avviata solo nella scheda attualmente attiva dopo che l'estensione è stata richiamata, in modo simile al funzionamento di activeTab. L'acquisizione viene mantenuta durante la navigazione nelle pagine all'interno della scheda e si interrompe quando la scheda viene chiusa o lo stream multimediale viene chiuso dall'estensione.

Parametri

  • opzioni

    CaptureOptions

    Configura lo stream multimediale restituito.

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (stream: LocalMediaStream) => void

    • flusso

      LocalMediaStream

getCapturedTabs()

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

Restituisce un elenco di schede che hanno richiesto l'acquisizione o che sono in fase di acquisizione, ovvero status != stopped e status != error. In questo modo, le estensioni possono informare l'utente che esiste un'acquisizione di schede esistente che impedirebbe l'acquisizione di una nuova scheda (o per evitare richieste ridondanti per la stessa scheda).

Parametri

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (result: CaptureInfo[]) => void

Resi

  • Promise<CaptureInfo[]>

    Chrome 116 e versioni successive

    Restituisce una Promise che si risolve con CaptureInfo[] per le schede acquisite.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getMediaStreamId()

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

Crea un ID stream per acquisire la scheda di destinazione. Simile al metodo chrome.tabCapture.capture(), ma restituisce un ID stream multimediale, anziché uno stream multimediale, alla scheda consumer.

Parametri

  • opzioni

    GetMediaStreamOptions facoltativo

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (streamId: string) => void

    • streamId

      stringa

Resi

  • Promise<string>

    Chrome 116 e versioni successive

    Restituisce una promessa che si risolve con il risultato. In caso di esito positivo, il risultato è una stringa opaca che può essere passata all'API getUserMedia() per generare uno stream multimediale corrispondente alla scheda di destinazione. Il streamId creato può essere utilizzato una sola volta e scade dopo pochi secondi se non viene utilizzato.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

Eventi

onStatusChanged

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

Evento attivato quando lo stato di acquisizione di una scheda cambia. In questo modo, gli autori delle estensioni possono monitorare lo stato di acquisizione delle schede per mantenere sincronizzati gli elementi UI, come le azioni sulla pagina.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (info: CaptureInfo) => void