Esta página foi traduzida pela API Cloud Translation.

Como gerenciar várias telas com a API Window Management

Receber informações sobre telas conectadas e posicionar janelas em relação a elas.

Thomas Steiner

API Window Management

A API Window Management permite enumerar as telas conectadas à máquina e colocar janelas em telas específicas.

Casos de uso sugeridos

Exemplos de sites que podem usar essa API:

Editores gráficos com várias janelas, como o Gimp, podem colocar várias ferramentas de edição em janelas posicionadas com precisão.
As mesas de negociação virtuais podem mostrar tendências de mercado em várias janelas, que podem ser visualizadas no modo de tela cheia.
Os apps de apresentação de slides podem mostrar anotações do apresentador na tela principal interna e a apresentação em um projetor externo.

Como usar a API Window Management

O problema

A abordagem testada pelo tempo para controlar janelas, Window.open(), infelizmente, não reconhece telas adicionais. Embora alguns aspectos dessa API pareçam um pouco arcaicos, como o parâmetro windowFeatures DOMString, ela tem sido útil ao longo dos anos. Para especificar a posição de uma janela, transmita as coordenadas como left e top (ou screenX e screenY, respectivamente) e transmita o tamanho desejado como width e height (ou innerWidth e innerHeight, respectivamente). Por exemplo, para abrir uma janela de 400×300 a 50 pixels da esquerda e 50 pixels da parte de cima, use este código:

const popup = window.open(
  'https://example.com/',
  'My Popup',
  'left=50,top=50,width=400,height=300',
);

Para saber mais sobre a tela atual, consulte a propriedade window.screen, que retorna um objeto Screen. Esta é a saída no meu MacBook Pro de 13 polegadas:

window.screen;
/* Output from my MacBook Pro 13″:
  availHeight: 969
  availLeft: 0
  availTop: 25
  availWidth: 1680
  colorDepth: 30
  height: 1050
  isExtended: true
  onchange: null
  orientation: ScreenOrientation {angle: 0, type: "landscape-primary", onchange: null}
  pixelDepth: 30
  width: 1680
*/

Como a maioria das pessoas que trabalham com tecnologia, tive que me adaptar à nova realidade do trabalho e montar meu home office pessoal. A minha é como a da foto abaixo. Se você tiver interesse, leia os detalhes completos sobre minha configuração. O iPad ao lado do meu MacBook está conectado ao laptop pelo Sidecar. Assim, sempre que preciso, posso transformar rapidamente o iPad em uma segunda tela.

Banco escolar em duas cadeiras. Em cima do banco escolar há caixas de sapatos que sustentam um laptop e dois iPads ao redor dele. — Uma configuração de várias telas.

Se eu quiser aproveitar a tela maior, posso colocar o pop-up da amostra de código acima na segunda tela. Eu faço assim:

popup.moveTo(2500, 50);

Essa é uma estimativa aproximada, já que não há como saber as dimensões da segunda tela. As informações de window.screen cobrem apenas a tela integrada, e não a tela do iPad. O width informado da tela integrada era de 1680 pixels. Portanto, mudar para 2500 pixels pode funcionar para mover a janela para o iPad, já que eu sei que ela está localizada à direita do meu MacBook. Como posso fazer isso no caso geral? Na verdade, há uma maneira melhor de fazer isso. Essa é a API Window Management.

Detecção de recursos

Para verificar se a API Window Management é compatível, use:

if ('getScreenDetails' in window) {
  // The Window Management API is supported.
}

A permissão `window-management`

Antes de usar a API Window Management, preciso pedir permissão ao usuário. A permissão window-management pode ser consultada com a API Permissions, assim:

let granted = false;
try {
  const { state } = await navigator.permissions.query({ name: 'window-management' });
  granted = state === 'granted';
} catch {
  // Nothing.
}

Enquanto os navegadores com o nome antigo e o novo estiverem em uso, use um código defensivo ao solicitar a permissão, como no exemplo abaixo.

async function getWindowManagementPermissionState() {
  let state;
  // The new permission name.
  try {
    ({ state } = await navigator.permissions.query({
      name: "window-management",
    }));
  } catch (err) {
    return `${err.name}: ${err.message}`;
  }
  return state;
}

document.querySelector("button").addEventListener("click", async () => {
  const state = await getWindowManagementPermissionState();
  document.querySelector("pre").textContent = state;
});

O navegador pode escolher mostrar a solicitação de permissão dinamicamente na primeira tentativa de usar qualquer um dos métodos da nova API. Continue lendo para saber mais.

A propriedade `window.screen.isExtended`

Para descobrir se mais de uma tela está conectada ao meu dispositivo, acesse a propriedade window.screen.isExtended. Ele retorna true ou false. Na minha configuração, ele retorna true.

window.screen.isExtended;
// Returns `true` or `false`.

O método `getScreenDetails()`

Agora que sei que a configuração atual é multitela, posso ter mais informações sobre a segunda tela usando Window.getScreenDetails(). Chamar essa função vai mostrar uma solicitação de permissão que pergunta se o site pode abrir e posicionar janelas na minha tela. A função retorna uma promessa que é resolvida com um objeto ScreenDetailed. No meu MacBook Pro 13 com um iPad conectado, isso inclui um campo screens com dois objetos ScreenDetailed:

await window.getScreenDetails();
/* Output from my MacBook Pro 13″ with the iPad attached:
{
  currentScreen: ScreenDetailed {left: 0, top: 0, isPrimary: true, isInternal: true, devicePixelRatio: 2, …}
  oncurrentscreenchange: null
  onscreenschange: null
  screens: [{
    // The MacBook Pro
    availHeight: 969
    availLeft: 0
    availTop: 25
    availWidth: 1680
    colorDepth: 30
    devicePixelRatio: 2
    height: 1050
    isExtended: true
    isInternal: true
    isPrimary: true
    label: "Built-in Retina Display"
    left: 0
    onchange: null
    orientation: ScreenOrientation {angle: 0, type: "landscape-primary", onchange: null}
    pixelDepth: 30
    top: 0
    width: 1680
  },
  {
    // The iPad
    availHeight: 999
    availLeft: 1680
    availTop: 25
    availWidth: 1366
    colorDepth: 24
    devicePixelRatio: 2
    height: 1024
    isExtended: true
    isInternal: false
    isPrimary: false
    label: "Sidecar Display (AirPlay)"
    left: 1680
    onchange: null
    orientation: ScreenOrientation {angle: 0, type: "landscape-primary", onchange: null}
    pixelDepth: 24
    top: 0
    width: 1366
  }]
}
*/

As informações sobre as telas conectadas estão disponíveis na matriz screens. Observe como o valor de left para o iPad começa em 1680, que é exatamente o width da tela integrada. Isso permite que eu determine exatamente como as telas são organizadas de forma lógica (uma ao lado da outra, uma sobre a outra etc.). Agora há dados para cada tela para mostrar se ela é isInternal ou isPrimary. A tela integrada não é necessariamente a tela principal.

O campo currentScreen é um objeto ativo correspondente ao window.screen atual. O objeto é atualizado em posicionamentos de janelas em várias telas ou mudanças de dispositivo.

Observação:a implementação mais recente da API do Chromium retorna rótulos de tela fornecidos pela plataforma subjacente, como "Built-in Retina Display", em vez de marcadores de posição menos descritivos, como "Internal Display 1".

O evento `screenschange`

A única coisa que falta agora é uma maneira de detectar quando a configuração da tela muda. Um novo evento, screenschange, faz exatamente isso: ele é acionado sempre que a constelação de tela é modificada. Observe que "telas" está no plural no nome do evento. Isso significa que o evento é acionado sempre que uma nova tela ou uma tela existente é conectada ou desconectada (fisicamente ou virtualmente, no caso do Sidecar).

É necessário procurar os detalhes da nova tela de forma assíncrona. O evento screenschange não fornece esses dados. Para consultar os detalhes da tela, use o objeto em tempo real de uma interface Screens em cache.

const screenDetails = await window.getScreenDetails();
let cachedScreensLength = screenDetails.screens.length;
screenDetails.addEventListener('screenschange', (event) => {
  if (screenDetails.screens.length !== cachedScreensLength) {
    console.log(
      `The screen count changed from ${cachedScreensLength} to ${screenDetails.screens.length}`,
    );
    cachedScreensLength = screenDetails.screens.length;
  }
});

O evento `currentscreenchange`

Se eu tiver interesse apenas nas mudanças na tela atual (ou seja, o valor do objeto currentScreen em tempo real), posso detectar o evento currentscreenchange.

const screenDetails = await window.getScreenDetails();
screenDetails.addEventListener('currentscreenchange', async (event) => {
  const details = screenDetails.currentScreen;
  console.log('The current screen has changed.', event, details);
});

O evento `change`

Por fim, se eu tiver interesse apenas em mudanças em uma tela específica, posso detectar o evento change dessa tela.

const firstScreen = (await window.getScreenDetails())[0];
firstScreen.addEventListener('change', async (event) => {
  console.log('The first screen has changed.', event, firstScreen);
});

Novas opções de tela cheia

Até agora, era possível solicitar que os elementos fossem mostrados no modo de tela inteira usando o método requestFullScreen() adequado. O método usa um parâmetro options em que é possível transmitir FullscreenOptions. Até agora, a única propriedade foi navigationUI. A API Window Management adiciona uma nova propriedade screen que permite determinar em qual tela iniciar a visualização em tela cheia. Por exemplo, se você quiser colocar a tela principal em tela cheia:

try {
  const primaryScreen = (await getScreenDetails()).screens.filter((screen) => screen.isPrimary)[0];
  await document.body.requestFullscreen({ screen: primaryScreen });
} catch (err) {
  console.error(err.name, err.message);
}

Polyfill

Não é possível usar o polyfill na API Window Management, mas você pode usar um shim para codificar exclusivamente para a nova API:

if (!('getScreenDetails' in window)) {
  // Returning a one-element array with the current screen,
  // noting that there might be more.
  window.getScreenDetails = async () => [window.screen];
  // Set to `false`, noting that this might be a lie.
  window.screen.isExtended = false;
}

Os outros aspectos da API, ou seja, os vários eventos de mudança de tela e a propriedade screen do FullscreenOptions, simplesmente não seriam acionados ou ignorados silenciosamente por navegadores que não oferecem suporte.

Demonstração

Se você é como eu, está de olho no desenvolvimento das várias criptomoedas. Na verdade, não, porque eu amo esse planeta, mas, para fins deste artigo, apenas suponha que eu amei. Para acompanhar as criptomoedas que tenho, desenvolvi um app da Web que me permite monitorar os mercados em todas as situações da vida, como no conforto da minha cama, onde tenho uma configuração decente de tela única.

Uma tela de TV enorme no fim de uma cama com as pernas do autor parcialmente visíveis. Na tela, uma mesa de negociação de criptomoedas falsa. — Relaxar e observar os mercados.

Como se trata de criptomoedas, os mercados podem ficar agitados a qualquer momento. Se isso acontecer, posso rapidamente me mudar para minha mesa, onde tenho uma configuração de várias telas. Posso clicar na janela de qualquer moeda e ver rapidamente todos os detalhes em uma visualização em tela cheia na tela oposta. Confira abaixo uma foto recente minha tirada durante o último massacre do YCY. Ele me pegou completamente desprevenido e me deixou com as mãos no rosto.

O autor com as mãos no rosto em pânico olhando para a mesa de negociação de criptomoedas falsa. — Panicky, testemunhando o banho de sangue da YCY.

Você pode testar a demonstração incorporada abaixo ou conferir o código-fonte no glitch.

Segurança e permissões

A equipe do Chrome projetou e implementou a API Window Management usando os princípios básicos definidos em Como controlar o acesso a recursos avançados da plataforma da Web, incluindo controle do usuário, transparência e ergonomia. A API Window Management expõe novas informações sobre as telas conectadas a um dispositivo, aumentando a superfície de impressão digital dos usuários, especialmente aqueles com várias telas conectadas constantemente aos dispositivos. Como uma mitigação dessa preocupação com a privacidade, as propriedades de tela expostas são limitadas ao mínimo necessário para casos de uso de posicionamento comuns. É necessária a permissão do usuário para que os sites recebam informações de multitelas e posicionem janelas em outras telas. Embora o Chromium retorne rótulos de tela detalhados, os navegadores podem retornar rótulos menos descritivos (ou até vazios).

Controle do usuário

O usuário tem controle total sobre a exposição da configuração. Eles podem aceitar ou recusar a permissão e revogar uma permissão concedida anteriormente pelo recurso de informações do site no navegador.

Controle empresarial

Os usuários do Chrome Enterprise podem controlar vários aspectos da API Window Management, conforme descrito na seção relevante das configurações de Atomic Policy Groups.

Transparência

A permissão para usar a API Window Management foi concedida e está exposta nas informações do site do navegador. Ela também pode ser consultada pela API Permissions.

Persistência de permissões

O navegador mantém as permissões concedidas. A permissão pode ser revogada pelas informações do site do navegador.

Feedback

A equipe do Chrome quer saber sobre sua experiência com a API Window Management.

Conte sobre o design da API

Há algo na API que não funciona como esperado? Ou há métodos ou propriedades ausentes que você precisa para implementar sua ideia? Tem dúvidas ou comentários sobre o modelo de segurança?

Envie um problema de especificação no repositório do GitHub correspondente ou adicione sua opinião a um problema existente.

Informar um 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 new.crbug.com. Inclua o máximo de detalhes possível, instruções simples para reprodução e insira Blink>Screen>MultiScreen na caixa Components. O Glitch é ótimo para compartilhar reprosagens rápidas e fáceis.

Mostrar suporte para a API

Você planeja usar a API Window Management? Seu apoio 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.

Compartilhe como você planeja usá-lo na discussão do Discourse do WICG.
Envie um tweet para @ChromiumDev usando a hashtag #WindowManagement e diga onde e como você está usando.
Peça a outros fornecedores de navegadores para implementar a API.

Links úteis

Agradecimentos

A especificação da API Window Management foi editada por Victor Costan, Joshua Bell e Mike Wasserman. A API foi implementada por Mike Wasserman e Adrienne Walker. Este artigo foi revisado por Joe Medley, François Beaufort e Kayce Basques. Agradecemos a Laura Torrent Puig pelas fotos.