Melhor compartilhamento de tela com o Foco condicional

François Beaufort

Elad Alon

A API Screen Capture permite que o usuário selecione uma guia, janela ou tela para capturar como um fluxo de mídia. Esse fluxo pode ser gravado ou compartilhado com outras pessoas pela rede. Esta documentação apresenta o foco condicional, um mecanismo para que apps da Web controlem se a guia ou janela capturada será focada quando a captura começar ou se a página de captura permanecerá focada.

Suporte ao navegador

O foco condicional está disponível no Chrome 109.

Contexto

Quando um app da Web começa a capturar uma guia ou janela, o navegador precisa decidir se a superfície capturada será trazida para o primeiro plano ou se a página de captura permanecerá focada. A resposta depende do motivo da chamada getDisplayMedia() e da superfície que o usuário seleciona.

Considere um app da Web de videoconferência hipotético. 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, foque a guia ou janela capturada.

No exemplo acima, o app da Web de videoconferência manteria o foco se compartilhasse uma apresentação de slides, permitindo que o usuário passasse os slides remotamente. No entanto, 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 promessa retornada getDiplayMedia() ser resolvida, você pode controlar se a guia ou janela capturada será focada ou não. Isso só pode ser feito se o usuário compartilhar 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 se deve focar, é 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");
}

É até possível decidir se deve 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 });

Você pode chamar setFocusBehavior() quantas vezes quiser antes que a promessa seja resolvida ou, no máximo, uma vez imediatamente após a resolução da promessa. A última invocação substitui todas as anteriores.

Mais precisamente:

• A promessa retornada getDisplayMedia() é resolvida em uma microtarefa. Chamar setFocusBehavior() após a conclusão dessa microtarefa gera um erro.
• Chamar setFocusBehavior() mais de um segundo após o início da captura é uma operação sem efeito.

Ou seja, os dois snippets a seguir vão falhar:

// 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 uma exceção nos seguintes casos:

• A faixa de vídeo do fluxo retornado por getDisplayMedia() não está "ao vivo".
• Após a promessa retornada getDisplayMedia() ser resolvida, se o usuário compartilhou uma tela (não uma guia ou janela).

Exemplo

Você pode usar o foco condicional executando a demonstração.

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 sobre suas experiências com o foco condicional.

Fale sobre o design

Há algo sobre o foco condicional que não funciona como esperado? Ou há métodos ou propriedades ausentes que você precisa 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 ou adicione suas ideias a um problema existente.

Problema com a implementação?

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

• Registre um bug em https://new.crbug.com. Inclua o máximo de detalhes possível e instruções para reprodução.

Mostrar suporte

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

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

Links úteis

• Especificação
• Vídeo explicativo
• Análise de TAG

Agradecimentos

Agradecemos a Rachel Andrew por analisar este documento.