Melhor compartilhamento de tela com o Foco condicional

François Beaufort
François Beaufort

Compatibilidade com navegadores

  • Chrome: 109
  • Borda: 109.
  • Firefox: incompatível.
  • Safari: incompatível.

Origem

A API Screen Capture permite que o usuário selecione uma guia, janela ou tela para capturar como um stream de mídia. Essa transmissão pode ser gravada ou compartilhada com outras pessoas na rede. Esta documentação apresenta o Foco condicional, um mecanismo para os aplicativos da Web controlarem se a guia ou janela capturada será focada quando a captura for iniciada ou se a página de captura permanecerá em foco.

Suporte ao navegador

O foco condicional está disponível a partir do Chrome 109.

Contexto

Quando um app da Web começa a capturar uma guia ou janela, o navegador toma uma decisão: a superfície capturada deve ser colocada em primeiro plano ou a página de captura deve permanecer em foco? A resposta depende do motivo da chamada de getDisplayMedia() e da plataforma que o usuário seleciona.

Considere um app da Web hipotético de videoconferência. Ao ler track.getSettings().displaySurface e possivelmente examinar o Identificador de captura, o app da Web de videoconferência pode entender o que o usuário escolheu compartilhar. Em seguida:

  • Se a guia ou janela capturada puder ser controlada remotamente, mantenha a videoconferência em foco.
  • Caso contrário, concentre o foco na guia ou janela capturada.

No exemplo acima, o app da Web de videoconferência manteria o foco ao compartilhar uma apresentação, permitindo que o usuário navegue pelos slides remotamente. mas, se o usuário escolhesse compartilhar um editor de texto, o app da Web de videoconferência mudaria imediatamente o foco para a guia ou janela capturada.

Como usar a API Conditional Focus

Instancie um CaptureController e transmita-o para getDisplayMedia(). Ao chamar setFocusBehavior() imediatamente após a resolução da promessa retornada de getDiplayMedia(), você pode controlar se a guia ou janela capturada será focada ou não. Isso só poderá ser feito se o usuário tiver compartilhado uma guia ou janela.

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");
}

Ao decidir o foco, é possível considerar o identificador de captura.

// 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");
}

Você pode até decidir se quer focar antes de chamar 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 });

É possível chamar setFocusBehavior() arbitrariamente várias vezes antes da resolução da promessa ou no máximo uma vez imediatamente após ela ser resolvida. A última invocação substitui todas as anteriores.

Mais precisamente: - A promessa retornada de getDisplayMedia() é resolvida em uma microtarefa. Chamar setFocusBehavior() depois que a microtarefa for concluída gera um erro. - Chamar setFocusBehavior() mais de um segundo após o início da captura não tem operação.

Ou seja, ambos os snippets a seguir falharão:

// 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");

Chamar setFocusBehavior() também gera estes casos:

  • a faixa de vídeo do stream retornado por getDisplayMedia() não está "live".
  • após a resolução da promessa retornada de getDisplayMedia(), se o usuário tiver compartilhado uma tela (não uma guia ou janela).

Exemplo

Você pode testar o foco condicional executando a demonstração no Glitch. Não se esqueça de conferir o código-fonte.

Detecção de recursos

Para verificar se CaptureController.setFocusBehavior() é compatível, use:

if (
  "CaptureController" in window &&
  "setFocusBehavior" in CaptureController.prototype
) {
  // CaptureController.setFocusBehavior() is supported.
}

Feedback

A equipe do Chrome e a comunidade de padrões da Web querem saber mais sobre suas experiências com o Foco condicional.

Conte-nos sobre o design

Alguma coisa no foco condicional não funciona como você esperava? Ou faltam métodos ou propriedades que você precisa para implementar sua ideia? Tem uma pergunta ou comentário sobre o modelo de segurança?

  • Registre um problema de especificação no repositório do GitHub (link em inglês) ou adicione sua opinião a um problema.

Problemas com a implementação?

Você encontrou um bug na implementação do Chrome? Ou a implementação é diferente das especificações?

  • Registre um bug em https://new.crbug.com. Certifique-se de incluir o máximo de detalhes possível e instruções simples para reproduzi-los. O Glitch funciona bem para compartilhar código.

Mostrar apoio

Você planeja usar o foco condicional? Seu apoio público ajuda a equipe do Chrome a priorizar recursos e mostra a outros fornecedores de navegadores como é essencial oferecer suporte a eles.

Envie um tweet para @ChromiumDev e informe onde e como você o está usando.

Agradecimentos

Imagem principal de Elena Taranenko.

Agradecemos a Rachel Andrew por revisar este artigo.