La condivisione di schede, finestre e schermi è già possibile sulla piattaforma web con l'API Screen Capture. Quando un'app web chiama getDisplayMedia(), Chrome chiede all'utente di condividere una scheda, una finestra o uno schermo con l'app web come video MediaStreamTrack.
Molte app web che utilizzano getDisplayMedia() mostrano all'utente un'anteprima video della superficie acquisita. Ad esempio, le app di videoconferenza spesso trasmettono questo video agli utenti remoti e lo visualizzano anche su un HTMLVideoElement locale, in modo che l'utente locale veda costantemente un'anteprima di ciò che sta condividendo.
Questa documentazione introduce la nuova API Captured Surface Control in Chrome, che consente alla tua app web di scorrere una scheda acquisita, nonché di leggere e scrivere il livello di zoom di una scheda acquisita.
Perché utilizzare Captured Surface Control?
Tutte le app di videoconferenza soffrono dello stesso inconveniente. Se l'utente vuole interagire con una scheda o una finestra acquisita, deve passare a quella superficie, allontanandosi dall'app di videoconferenza. Ciò presenta alcune sfide:
- L'utente non può vedere contemporaneamente l'app acquisita e i feed video degli utenti da remoto, a meno che non utilizzi la funzionalità Picture in picture o finestre separate affiancate per la scheda della videoconferenza e la scheda condivisa. Su uno schermo più piccolo, questa operazione potrebbe essere difficile.
- L'utente è gravato dalla necessità di passare dall'app di videoconferenza alla superficie acquisita.
- L'utente perde l'accesso ai controlli esposti dall'app di videoconferenza mentre non la utilizza. Ad esempio, un'app di chat incorporata, le reazioni con emoji, le notifiche relative agli utenti che chiedono di partecipare alla chiamata, i controlli multimediali e di layout e altre utili funzionalità di videoconferenza.
- Il relatore non può delegare il controllo ai partecipanti remoti. Ciò porta allo scenario fin troppo familiare in cui gli utenti da remoto chiedono al relatore di cambiare slide, scorrere un po' verso l'alto e il basso o regolare il livello di zoom.
L'API Captured Surface Control risolve questi problemi.
Come si utilizza il controllo della superficie acquisita?
L'utilizzo di Controllo della superficie acquisita richiede alcuni passaggi, ad esempio l'acquisizione esplicita di una scheda del browser e l'ottenimento dell'autorizzazione dell'utente prima di poter scorrere e ingrandire la scheda acquisita.
Acquisire una scheda del browser
Inizia chiedendo all'utente di scegliere una superficie da condividere utilizzando getDisplayMedia() e, nel frattempo, associa un oggetto CaptureController alla sessione di acquisizione. A breve utilizzeremo questo oggetto per controllare la superficie acquisita.
const controller = new CaptureController(); const stream = await navigator.mediaDevices.getDisplayMedia({ controller }); A questo punto, genera un'anteprima locale della superficie acquisita sotto forma di elemento <video>:
const previewTile = document.querySelector('video'); previewTile.srcObject = stream; Se l'utente sceglie di condividere una finestra o uno schermo, per il momento non è possibile, ma se sceglie di condividere una scheda, possiamo procedere.
const [track] = stream.getVideoTracks(); if (track.getSettings().displaySurface !== 'browser') { // Bail out early if the user didn't pick a tab. return; } Prompt di autorizzazione
La prima invocazione di forwardWheel(), increaseZoomLevel(), decreaseZoomLevel() o resetZoomLevel() su un determinato oggetto CaptureController produce una richiesta di autorizzazione. Se l'utente concede l'autorizzazione, sono consentite ulteriori chiamate di questi metodi.
Per mostrare all'utente una richiesta di autorizzazione è necessaria un'azione dell'utente, pertanto l'app deve chiamare i metodi menzionati solo se dispone già dell'autorizzazione o in risposta a un'azione dell'utente, ad esempio un click su un pulsante pertinente nell'app web.
Scorri
Utilizzando forwardWheel(), un'app di acquisizione può inoltrare gli eventi della rotellina da un elemento sorgente all'interno dell'app di acquisizione stessa alla finestra dell'app acquisita. Questi eventi non sono distinguibili dall'interazione diretta dell'utente per l'app acquisita.
Supponendo che l'app di acquisizione utilizzi un elemento <video> chiamato "previewTile", il seguente codice mostra come inoltrare gli eventi della rotellina alla scheda acquisita:
const previewTile = document.querySelector('video'); try { // Relay the user's action to the captured tab. await controller.forwardWheel(previewTile); } catch (error) { // Inspect the error. // ... } Il metodo forwardWheel() accetta un singolo input che può essere uno dei seguenti:
- Un elemento HTML da cui gli eventi della rotellina verranno inoltrati alla scheda acquisita.
null, a indicare che l'inoltro deve essere interrotto.
Una chiamata riuscita a forwardWheel() sostituisce le chiamate precedenti.
La promessa restituita da forwardWheel() può essere rifiutata nei seguenti casi:
- Se la sessione di acquisizione non è ancora iniziata o è già terminata.
- Se l'utente non ha concesso l'autorizzazione pertinente.
Zoom
L'interazione con il livello di zoom della scheda acquisita avviene tramite le seguenti interfacce API CaptureController:
getSupportedZoomLevels()
Questo metodo restituisce un elenco dei livelli di zoom supportati dal browser per il tipo di superficie acquisita. I valori di questo elenco sono rappresentati come percentuale rispetto al "livello di zoom predefinito", definito come 100%. L'elenco è monotonicamente crescente e contiene il valore 100.
Questo metodo può essere chiamato solo per i tipi di superfici di visualizzazione supportati, il che al momento significa solo per le schede.
controller.getSupportedZoomLevels() può essere chiamato se sussistono le seguenti condizioni:
controllerè associato a un'acquisizione attiva.- La registrazione è di una scheda.
In caso contrario, verrà generato un errore.
L'autorizzazione "captured-surface-control" non è necessaria per chiamare questo metodo.
zoomLevel
Questo attributo di sola lettura contiene il livello di zoom attuale della scheda acquisita. È un attributo nullable e contiene null se il tipo di superficie acquisita non ha una definizione significativa del livello di zoom. Al momento, il livello di zoom è definito solo per le schede, non per le finestre o gli schermi.
Al termine dell'acquisizione, l'attributo conterrà l'ultimo valore del livello di zoom.
L'autorizzazione "captured-surface-control" non è necessaria per leggere questo attributo.
onzoomlevelchange
Questo gestore di eventi facilita l'ascolto delle modifiche al livello di zoom della scheda acquisita. Questi eventi si verificano:
- Quando l'utente interagisce con il browser per modificare manualmente il livello di zoom della scheda acquisita.
- In risposta alle chiamate dell'app di acquisizione ai metodi di impostazione dello zoom (descritti di seguito).
L'autorizzazione "captured-surface-control" non è necessaria per leggere questo attributo.
increaseZoomLevel(), decreaseZoomLevel() e resetZoomLevel()
Questi metodi consentono di manipolare il livello di zoom della scheda acquisita.
increaseZoomLevel() e decreaseZoomLevel() modificano il livello di zoom al livello successivo o precedente, rispettivamente, in base all'ordinamento restituito da getSupportedZoomLevels(). resetZoomLevel() imposta il valore su 100.
Per chiamare questi metodi è necessaria l'autorizzazione "captured-surface-control" . Se l'app di acquisizione non dispone di questa autorizzazione, all'utente verrà chiesto di concederla o negarla.
Tutti questi metodi restituiscono una promessa che viene risolta se la chiamata ha esito positivo e rifiutata in caso contrario. Tra le possibili cause di rifiuto rientrano:
- Autorizzazione mancante.
- Chiamata effettuata prima dell'inizio dell'acquisizione.
- Chiamata effettuata dopo la fine dell'acquisizione.
- Chiamato su un
controllerassociato a un'acquisizione di un tipo di superficie di visualizzazione non supportato. ovvero qualsiasi cosa tranne l'acquisizione della scheda. - Tentativi di aumentare o diminuire oltre il valore massimo o minimo, rispettivamente.
In particolare, è consigliabile evitare di chiamare il numero decreaseZoomLevel() se controller.zoomLevel == controller.getSupportedZoomLevels().at(0) e di proteggere le chiamate al numero increaseZoomLevel() in modo simile con .at(-1).
L'esempio seguente mostra come consentire all'utente di aumentare il livello di zoom di una scheda acquisita direttamente dall'app di acquisizione:
const zoomIncreaseButton = document.getElementById('zoomInButton'); zoomIncreaseButton.addEventListener('click', async (event) => { if (controller.zoomLevel >= controller.getSupportedZoomLevels().at(-1)) { return; } try { await controller.increaseZoomLevel(); } catch (error) { // Inspect the error. // ... } }); Il seguente esempio mostra come reagire alle modifiche del livello di zoom di una scheda acquisita:
controller.addEventListener('zoomlevelchange', (event) => { const zoomLevelLabel = document.querySelector('#zoomLevelLabel'); zoomLevelLabel.textContent = `${controller.zoomLevel}%`; }); Rilevamento delle funzionalità
Per verificare se le API Captured Surface Control sono supportate, utilizza:
if (!!window.CaptureController?.prototype.forwardWheel) { // CaptureController forwardWheel() is supported. } È altrettanto possibile utilizzare una qualsiasi delle altre superfici dell'API Captured Surface Control, ad esempio increaseZoomLevel o decreaseZoomLevel, o persino controllarle tutte.
Supporto browser
Il controllo della superficie acquisita è disponibile solo su computer a partire da Chrome 136.
Sicurezza e privacy
Il criterio relativo alle autorizzazioni di "captured-surface-control" ti consente di gestire il modo in cui l'app di acquisizione e gli iframe di terze parti incorporati hanno accesso al controllo della superficie acquisita. Per comprendere i compromessi in termini di sicurezza, consulta la sezione Considerazioni su privacy e sicurezza della spiegazione del controllo della superficie acquisita.
Demo
Puoi provare il controllo della superficie acquisita eseguendo la demo.
Feedback
Il team di Chrome e la community degli standard web vogliono conoscere la tua esperienza con il controllo della superficie acquisita.
Descrivi il design
C'è qualcosa in merito alla funzionalità di acquisizione della superficie catturata che non funziona come previsto? Oppure mancano metodi o proprietà che ti servono per implementare la tua idea? Hai una domanda o un commento sul modello di sicurezza? Invia una segnalazione relativa alle specifiche nel repository GitHub o aggiungi i tuoi commenti a una segnalazione esistente.
Problemi con l'implementazione?
Hai trovato un bug nell'implementazione di Chrome? L'implementazione è diversa dalla specifica? Invia una segnalazione di bug all'indirizzo https://new.crbug.com. Assicurati di includere il maggior numero di dettagli possibile, nonché le istruzioni per la riproduzione.