L'API Screen Capture consente all'utente di selezionare una scheda, una finestra o una schermata da acquisire come stream multimediale. Questo stream può essere registrato o condiviso con altri utenti sulla rete. Questa documentazione introduce la messa a fuoco condizionale, un meccanismo che consente alle app web di controllare se impostare lo stato attivo sulla scheda o sulla finestra acquisita all'avvio dell'acquisizione o se la pagina di acquisizione rimane attiva.
Supporto del browser
La funzionalità Conditional Focus è disponibile in Chrome 109.
Contesto
Quando un'app web inizia ad acquisire una scheda o una finestra, il browser deve prendere una decisione: la superficie acquisita deve essere messa in primo piano o la pagina di acquisizione deve rimanere attiva? La risposta dipende dal motivo per cui hai chiamato getDisplayMedia() e dalla piattaforma che l'utente selezionerà.
Prendi in considerazione un'app web per videoconferenze ipotetica. Leggendo track.getSettings().displaySurface ed esaminando potenzialmente l'handle di acquisizione, l'app web per videoconferenze può capire cosa ha scelto di condividere l'utente. Quindi:
- Se la scheda o la finestra acquisita può essere controllata da remoto, mantieni a fuoco la videoconferenza.
- Altrimenti, imposta lo stato attivo sulla scheda o sulla finestra acquisita.
Nell'esempio precedente, l'app web per videoconferenze manterrà lo stato attivo se si condivide una presentazione, consentendo all'utente di scorrere le slide da remoto; ma se l'utente sceglie di condividere un editor di testo, l'app web di videoconferenza passa immediatamente lo stato attivo alla scheda o alla finestra acquisita.
Utilizzo dell'API Conditional Focus
Crea un'istanza di CaptureController e passala a getDisplayMedia(). Se chiami setFocusBehavior() subito dopo la risoluzione della promessa restituita da getDiplayMedia(), puoi controllare se lo stato attivo della scheda o della finestra acquisita è impostato o meno. Questa operazione può essere eseguita solo se l'utente ha condiviso una scheda o una finestra.
const controller = new CaptureController();
// Prompt the user to share a tab, a window or a screen.
const stream =
await navigator.mediaDevices.getDisplayMedia({ controller });
const [track] = stream.getVideoTracks();
const displaySurface = track.getSettings().displaySurface;
if (displaySurface == "browser") {
// Focus the captured tab.
controller.setFocusBehavior("focus-captured-surface");
} else if (displaySurface == "window") {
// Do not move focus to the captured window.
// Keep the capturing page focused.
controller.setFocusBehavior("focus-capturing-application");
}
Quando decidi se concentrarti, è possibile prendere in considerazione l'handle di acquisizione.
// Retain focus if capturing a tab dialed to example.com.
// Focus anything else.
const origin = track.getCaptureHandle().origin;
if (displaySurface == "browser" && origin == "https://example.com") {
controller.setFocusBehavior("focus-capturing-application");
} else if (displaySurface != "monitor") {
controller.setFocusBehavior("focus-captured-surface");
}
È anche possibile decidere se concentrarsi prima di chiamare il numero getDisplayMedia().
// Focus the captured tab or window when capture starts.
const controller = new CaptureController();
controller.setFocusBehavior("focus-captured-surface");
// Prompt the user to share their screen.
const stream =
await navigator.mediaDevices.getDisplayMedia({ controller });
Puoi chiamare setFocusBehavior() arbitrariamente molte volte prima della risoluzione della promessa o al massimo una volta immediatamente dopo la sua risoluzione. L'ultima chiamata sostituisce tutte le chiamate precedenti.
Più precisamente:
- La promessa restituita da getDisplayMedia() si risolve su un microattività. La chiamata a setFocusBehavior() al termine del microtask genera un errore.
- Chiamare setFocusBehavior() più di un secondo dopo l'avvio dell'acquisizione è autonomo.
Ciò significa che entrambi i seguenti snippet non andranno a buon fine:
// Prompt the user to share their screen.
const stream =
await navigator.mediaDevices.getDisplayMedia({ controller });
// Too late, because it follows the completion of the task
// on which the getDisplayMedia() promise resolved.
// This will throw.
setTimeout(() => {
controller.setFocusBehavior("focus-captured-surface");
});
// Prompt the user to share their screen.
const stream =
await navigator.mediaDevices.getDisplayMedia({ controller });
const start = new Date();
while (new Date() - start <= 1000) {
// Idle for ≈1s.
}
// Because too much time has elapsed, the browser will have
// already decided whether to focus.
// This fails silently.
controller.setFocusBehavior("focus-captured-surface");
La chiamata a setFocusBehavior() genera anche nei seguenti casi:
- la traccia video dello stream restituita da
getDisplayMedia()non è "live". - al termine della promessa restituita da
getDisplayMedia(), se l'utente ha condiviso una schermata (non una scheda o una finestra).
Esempio
Puoi giocare con Focus condizionale eseguendo la demo su Glitch. Assicurati di controllare il codice sorgente.
Rilevamento delle funzionalità
Per verificare se CaptureController.setFocusBehavior() è supportato, utilizza:
if (
"CaptureController" in window &&
"setFocusBehavior" in CaptureController.prototype
) {
// CaptureController.setFocusBehavior() is supported.
}
Feedback
Il team di Chrome e la community degli standard web vogliono conoscere le tue esperienze con la funzionalità Conditional Focus.
Descrivi il design
C'è qualcosa nel focus condizionale che non funziona come previsto? Oppure mancano metodi o proprietà di cui hai bisogno per implementare la tua idea? Hai domande o commenti sul modello di sicurezza?
- Segnala un problema relativo alle specifiche nel repository GitHub o aggiungi la tua opinione su un problema esistente.
Problemi con l'implementazione?
Hai trovato un bug nell'implementazione di Chrome? Oppure l'implementazione è diversa dalle specifiche?
- Segnala un bug all'indirizzo https://new.crbug.com. Assicurati di includere il maggior numero possibile di dettagli e di semplici istruzioni per la riproduzione. Glitch funziona bene per la condivisione di codice.
Mostra supporto
Hai intenzione di utilizzare la messa a fuoco condizionale? Il tuo supporto pubblico aiuta il team di Chrome a dare la priorità alle funzionalità e mostra agli altri fornitori di browser quanto sia fondamentale supportarle.
Invia un tweet a @ChromiumDev e facci sapere dove e come lo utilizzi.
Link utili
Ringraziamenti
Immagine promozionale di Elena Taranenko.
Grazie a Rachel Andrew per aver letto questo articolo.