La condivisione di schede, finestre e schermate è 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 in streaming agli utenti remoti e lo visualizzano anche su un HTMLVideoElement locale, in modo che l'utente locale possa vedere 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 il controllo delle aree acquisite?
Tutte le app di videoconferenza presentano lo stesso svantaggio. 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 remoti, a meno che non utilizzi la funzionalità Picture in picture o finestre separate una accanto all'altra 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 quando non è in uso, ad esempio un'app di chat incorporata, reazioni con emoji, notifiche relative agli utenti che chiedono di partecipare alla chiamata, controlli multimediali e di layout e altre funzionalità utili per le videoconferenze.
- Il presentatore non può delegare il controllo ai partecipanti remoti. Questo porta allo scenario fin troppo familiare in cui gli utenti remoti chiedono al presentatore di cambiare la diapositiva, scorrere un po' verso l'alto e verso il basso o regolare il livello di zoom.
L'API Captured Surface Control risolve questi problemi.
Come faccio a utilizzare il controllo della superficie acquisita?
Per utilizzare correttamente il controllo della superficie acquisita sono necessari alcuni passaggi, ad esempio acquisire esplicitamente una scheda del browser e ottenere l'autorizzazione dell'utente prima di poter scorrere e aumentare lo zoom della scheda acquisita.
Acquisire una scheda del browser
Per iniziare, chiedi all'utente di scegliere una superficie da condividere utilizzando getDisplayMedia() e, nel processo, 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 });
Successivamente, crea 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 una schermata, per il momento non rientra nell'ambito, 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;
}
Richiesta di autorizzazione
La prima chiamata di forwardWheel(), increaseZoomLevel(), decreaseZoomLevel() o resetZoomLevel() su un determinato oggetto CaptureController genera una richiesta di autorizzazione. Se l'utente concede l'autorizzazione, sono consentite ulteriori invocazioni di questi metodi.
Per mostrare una richiesta di autorizzazione all'utente è necessario un gesto dell'utente, pertanto l'app deve chiamare i metodi sopra indicati solo se dispone già dell'autorizzazione o in risposta a un gesto 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 rotella da un elemento di origine all'interno dell'app di acquisizione stessa al viewport della scheda acquisita. Per l'app acquisita, questi eventi non sono distinguibili dall'interazione diretta dell'utente.
Supponendo che l'app di acquisizione utilizzi un elemento <video> denominato "previewTile", il seguente codice mostra come inoltrare gli eventi di invio della rotella 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 a forwardWheel() andata a buon fine 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à stata interrotta.
- 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 in questo elenco sono rappresentati come percentuale rispetto al "livello di zoom predefinito", definito come 100%. L'elenco è in ordine crescente e contiene il valore 100.
Questo metodo può essere chiamato solo per i tipi di piattaforme di visualizzazione supportati, che al momento significa solo per le schede.
controller.getSupportedZoomLevels() può essere chiamato se si verificano le seguenti condizioni:
controllerè associato a una cattura attiva.- Lo screenshot è 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 corrente 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 e non per le finestre o le schermate.
Al termine dell'acquisizione, l'attributo conterrà l'ultimo valore del livello di zoom.
L'autorizzazione "captured-surface-control" non è necessaria per la lettura di questo attributo.
onzoomlevelchange
Questo gestore eventi facilita l'ascolto delle modifiche al livello di zoom della scheda acquisita. Ciò si verifica:
- 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 rispettivamente su quello successivo o precedente, in base all'ordinamento restituito da getSupportedZoomLevels(). resetZoomLevel() imposta il valore su 100.
L'autorizzazione "captured-surface-control" è obbligatoria per chiamare questi metodi. 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 va a buon fine e rifiutata in caso contrario. Ecco alcuni possibili motivi di rifiuto:
- Autorizzazione mancante.
- Chiamata prima dell'inizio dell'acquisizione.
- Chiamata dopo il termine dell'acquisizione.
- Chiamata su un
controllerassociato a un'acquisizione di un tipo di superficie di visualizzazione non supportato. (ovvero qualsiasi cosa diversa dalla cattura di schede). - Tenta di aumentare o diminuire oltre il valore massimo o minimo, rispettivamente.
In particolare, ti consigliamo di evitare di chiamare decreaseZoomLevel() se controller.zoomLevel == controller.getSupportedZoomLevels().at(0) e di proteggere le chiamate a 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 di funzionalità
Per verificare se le API Captured Surface Control sono supportate, utilizza:
if (!!window.CaptureController?.prototype.forwardWheel) {
// CaptureController forwardWheel() is supported.
}
È ugualmente possibile utilizzare qualsiasi altra API Captured Surface Control, ad esempio increaseZoomLevel o decreaseZoomLevel, o persino controllarle tutte.
Supporto browser
Il controllo delle aree acquisite è disponibile a partire da Chrome 136 solo su computer.
Sicurezza e privacy
I criteri di autorizzazione "captured-surface-control" ti consentono di gestire il modo in cui l'app di acquisizione e gli iframe di terze parti incorporati hanno accesso al controllo delle aree acquisite. Per comprendere i compromessi in termini di sicurezza, consulta la sezione Considerazioni sulla privacy e sulla sicurezza della pagina informativa sul controllo delle aree acquisite.
Demo
Puoi provare il controllo delle superfici acquisite eseguendo la demo su Glitch. Assicurati di controllare il codice sorgente.
Feedback
Il team di Chrome e la community degli standard web vogliono conoscere le tue esperienze con il controllo delle aree acquisite.
Parlaci del design
C'è qualcosa in merito a Captured Surface Capture che non funziona come previsto? Oppure mancano metodi o proprietà necessari 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 il tuo parere a una segnalazione esistente.
Problemi con l'implementazione?
Hai trovato un bug nell'implementazione di Chrome? Oppure 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. Glitch è ideale per condividere bug riproducibili.