Como gerenciar janelas

Uma PWA fora do navegador gerencia a própria janela. Neste capítulo, você entenderá as APIs e os recursos para gerenciar uma janela no sistema operacional.

Janela do PWA

A execução na sua própria janela, gerenciada pelo PWA, tem todas as vantagens e responsabilidades de qualquer janela desse sistema operacional, como:

• A capacidade de redimensionar e mover a janela em sistemas operacionais de várias janelas, como Windows ou ChromeOS.
• Compartilhar a tela com outras janelas de apps, como no modo dividido do iPadOS ou de tela dividida do Android.
• Aparecem em bases, barras de tarefas e no menu "alt-tab" em computadores e em listas de janelas multitarefa em dispositivos móveis.
• A capacidade de minimizar, mover a janela entre telas e áreas de trabalho e fechá-la a qualquer momento.

Mover e redimensionar a janela

A janela da PWA pode ter qualquer tamanho e ser posicionada em qualquer lugar da tela em sistemas operacionais para computadores. Por padrão, quando o usuário abre o PWA pela primeira vez após a instalação, ele recebe um tamanho de janela padrão de uma porcentagem da tela atual, com uma resolução máxima de 1920x1080 posicionada no canto superior esquerdo da tela.

O usuário pode mover e redimensionar a janela, e o navegador vai se lembrar da última preferência. Assim, na próxima vez que o usuário abrir o app, a janela vai manter o tamanho e a posição do uso anterior.

Não é possível definir o tamanho e a posição preferidos da PWA no manifesto. Só é possível reposicionar e redimensionar a janela usando a API JavaScript. No seu código, é possível mover e redimensionar sua própria janela do PWA usando as funções moveTo(x, y) e resizeTo(x, y) do objeto window.

Por exemplo, você pode redimensionar e mover a janela do PWA quando ele for carregado usando:

document.addEventListener("DOMContentLoaded", event => {
   // we can move only if we are not in a browser's tab
   isBrowser = matchMedia("(display-mode: browser)").matches;
   if (!isBrowser) {
      window.moveTo(16, 16);
      window.resizeTo(800, 600);
   }
});

É possível consultar o tamanho e a posição da tela atual usando o objeto window.screen. Também é possível detectar quando a janela é redimensionada usando o evento resize do objeto window. Não há um evento para capturar o movimento da janela. Portanto, sua opção é consultar a posição com frequência.

Observação : em vez de mover e redimensionar a janela de maneira absoluta, você pode mover de forma relativa e redimensionar usando moveBy() e resizeBy().

Observação: em dispositivos móveis, mover ou redimensionar a janela não faz nenhuma mudança na tela.

Navegação para outros sites

Se você quiser enviar o usuário para um site externo que esteja fora do escopo do seu PWA, poderá fazer isso com um elemento HTML <a href> padrão, usando location.href ou abrindo uma nova janela em plataformas compatíveis.

Atualmente, se o PWA estiver instalado em todos os navegadores, quando você acessar um URL fora do escopo do manifesto, o mecanismo do PWA renderizará um navegador no app no contexto da janela.

Alguns recursos dos navegadores no app são:

• Eles aparecem acima do conteúdo.
• Elas têm uma barra de URL estática que mostra a origem atual, o título da janela e um menu. Normalmente, o tema deles é o theme_color do manifesto.
• No menu contextual, você pode abrir esse URL no navegador.
• Os usuários podem fechar o navegador ou voltar.

Observação: enquanto o navegador no app está na tela, o PWA fica aguardando em segundo plano, como se outra janela estivesse o obscurecendo.

No iOS e no iPadOS, o navegador no app usa o SafariViewController, um mecanismo de renderização do Safari isolado do armazenamento da PWA. Portanto, se o usuário tiver uma sessão no Safari, ela não aparecerá no PWA, mas aparecerá em um navegador no app.

Fluxos de autorização

Muitos fluxos de autenticação e autorização da Web envolvem o redirecionamento do usuário para um URL com origem diferente para adquirir um token que retornará à origem do PWA, como o uso do OAuth 2.0.

Nesses casos, o navegador no app segue este processo:

1. O usuário abre seu PWA e clica em "Fazer login".
2. O PWA redireciona o usuário para um URL fora do escopo do PWA. Assim, o mecanismo de renderização abre um navegador no app.
3. O usuário pode cancelar o navegador no app e voltar para o PWA a qualquer momento.
4. O usuário faz login no navegador no app. O servidor de autenticação redireciona o usuário para a origem da PWA, enviando o token como um argumento.
5. O navegador no app fecha automaticamente quando detecta um URL que faz parte do escopo do PWA.
6. O mecanismo redireciona a navegação da janela principal da PWA para o URL que o servidor de autenticação acessou no navegador no app.
7. O PWA recebe e armazena o token, além de renderizar o PWA.

Como forçar a navegação de um navegador

Se você quiser forçar a abertura do navegador com um URL e não um navegador no app, use o destino _blank dos elementos <a href>. Isso funciona apenas em PWAs para computador. Em dispositivos móveis, não há a opção de abrir um navegador com um URL.

function openBrowser(url) {
    window.open("url", "_blank", "");
}

Abrir novas janelas

Em computadores, os usuários podem abrir mais de uma janela do mesmo PWA. Cada janela será uma navegação diferente para o mesmo start_url, como se você estivesse abrindo duas guias do navegador com o mesmo URL. No menu do PWA, os usuários podem selecionar "File" e "New window". No código do PWA, você pode abrir uma nova janela com a função open(). Consulte a documentação para mais detalhes.

function openNewWindow() {
    window.open("/", "new-window", "width=600,height=600");
}

Chamar open() em uma janela de PWA no iOS ou iPadOS retorna null e não abre uma janela. A abertura de novas janelas no Android cria um novo navegador no app para o URL, mesmo que o URL esteja no escopo do PWA, que normalmente não aciona uma experiência de navegação externa.

Aviso: o segundo argumento de open() é o nome da janela. Se o nome que você usou já estiver aberto, o mecanismo vai substituir a janela aberta com esse nome por uma nova navegação. Se você quiser sempre abrir uma nova janela, use valores de string diferentes para um nome.

As funções open(), moveTo() e resizeTo() não precisam do prefixo window. ao escrever JavaScript porque window é o objeto global. Basta chamar moveTo(0, 0). No entanto, chamar window.moveTo(0, 0) facilita a compreensão do código.

Título da janela

O elemento <title> foi usado principalmente para SEO porque o espaço em uma guia do navegador é limitado. Quando você muda do navegador para a janela em um PWA, todo o espaço da barra de título fica disponível.

É possível definir o conteúdo da barra de título:

• Estático no elemento <title> HTML.
• Mudança dinâmica da propriedade de string document.title a qualquer momento.

Em PWAs para computador, o título é essencial e é usado na barra de título da janela e, às vezes, no gerenciador de tarefas ou na seleção de multitarefas. Se você tiver um aplicativo de página única, atualize o título em todas as rotas.

Observação: para reduzir o phishing em PWAs, alguns navegadores para computador podem ter medidas adicionais no título da janela. Por exemplo, se você não usar o nome do app no título, o navegador poderá adicionar um prefixo com o nome da PWA. Outros navegadores podem renderizar a origem atual na barra de título por alguns segundos quando você muda o título para destacar para onde o usuário navegou.

Modo com guias

Um recurso experimental, conhecido como modo de guias, permite que o PWA tenha um design baseado em guias semelhante a um navegador da Web. Nesse caso, o usuário pode ter várias guias abertas do mesmo PWA, mas todas vinculadas na mesma janela do sistema operacional, como mostrado no vídeo a seguir:

Saiba mais sobre esse recurso experimental em Modo de app com guias para PWA.

Observação: no capítulo Experimental, você vai saber como começar a usar os recursos experimentais.

Sobreposição de controles da janela

Já mencionamos que você pode mudar o título da janela definindo o valor do elemento <title> ou da propriedade document.title. Mas ele sempre é um valor de string. E se pudéssemos projetar a barra de título como quisermos, com HTML, CSS e imagens? É aí que entra a sobreposição de controles de janela, um novo recurso experimental no Microsoft Edge e no Google Chrome para PWAs para computador.

Observação: os recursos de sobreposição de modo de guias e controles de janela definem novos valores para o membro display do manifesto. Para criar compatibilidade com todos os dispositivos, o grupo de manifesto criou uma maneira de substituir a cadeia de fallback display. Assim, você pode especificar qual valor de display usar se a primeira opção não estiver disponível. Leia mais sobre isso em Como se preparar para os modos de exibição do futuro.

Saiba mais sobre esse recurso em Personalizar a sobreposição de controles da janela da barra de título do PWA.

Como gerenciar janelas

Com várias telas, os usuários vão querer usar todo o espaço disponível. Exemplo:

• 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.

A API Window Management permite que os PWAs façam isso e muito mais.

Acessando detalhes da tela

A API Window Management adiciona um novo método, window.getScreenDetails(), que retorna um objeto com telas como uma matriz imutável de telas anexadas. Também há um objeto em tempo real acessível em ScreenDetails.currentScreen, correspondente ao window.screen atual.

Em alguns navegadores, chamar window.getScreenDetails() exige que o usuário conceda permissão aos seus PWAs.

O objeto retornado também aciona um evento screenschange quando a matriz screens muda. Isso não acontece quando os atributos em telas individuais são alterados. Telas individuais, window.screen ou uma tela na matriz screens, também disparam um evento change quando os atributos mudam.

// Request an object with a screen objects
const screenDetails = await window.getScreenDetails();
screenDetails.screens[0].isPrimary;  // e.g. true
screenDetails.screens[0].isInternal;  // e.g. true
screenDetails.screens[0].label;  // e.g. 'Samsung Electric Company 28"'

// Access the live object corresponding to the current `window.screen`.
// The object is updated on cross-screen window placements or device changes.
screenDetails.currentScreen;
screenDetails.addEventListener('screenschange', function() {
 // NOTE: Does not fire on changes to attributes of individual screens.
  const screenCount = screenDetails.screens.length;
  const currentScreen screenDetails.currentScreen.id;
});

Se o usuário ou o sistema operacional mover a janela do PWA de uma tela para outra, um evento currentscreenchange também será disparado no objeto de detalhes da tela.

Observação: você também pode usar a API Presentation para mostrar conteúdo da Web em dispositivos de apresentação grandes, como projetores e TVs conectadas à rede.

Compatibilidade com navegadores

• 47
• 79
• x
• x

Origem

Wake lock de tela

Imagine que você está na cozinha seguindo uma receita no seu tablet. Você acabou de preparar os ingredientes. Suas mãos estão sujas, e você volta para o dispositivo para ler a próxima etapa. Desastre! A tela ficou preta. A API Screen Wake Lock permite que um PWA impeça que as telas sejam escurecidas, entrem em suspensão ou sejam bloqueadas, permitindo que os usuários parem, iniciem, saiam e voltem sem se preocupar.

// Request a screen wake lock
const wakeLock = await navigator.wakeLock.request();

// Listen for wake lock release
wakeLock.addEventListener('release', () => {
 console.log(`Screen Wake Lock released: ${wakeLock.released}`);
});
// Manually release the wake lock
wakeLock.release();

Teclado virtual

Dispositivos baseados em toque, como smartphones e tablets, oferecem um teclado virtual na tela para que o usuário possa digitar quando os elementos de formulário do PWA estiverem em foco.

Graças à API VirtualKeyboard, seu PWA agora pode ter mais controle do teclado em plataformas compatíveis usando a interface navigator.virtualKeyboard, incluindo:

• Como mostrar e ocultar o teclado virtual com as funções navigator.virtualKeyboard.show() e navigator.virtualKeyboard.hide().
• Informar ao navegador que você está cuidando do fechamento do teclado virtual definindo navigator.virtualKeyboard.overlaysContent como true.
• Saber quando o teclado aparece e desaparece com o evento geometrychange de navigator.virtualKeyboard.
• Definir a política do teclado virtual ao editar elementos do host (usando contenteditable) com o atributo HTML virtualkeyboardpolicy. Uma política permite que você decida se quer que o teclado virtual seja processado automaticamente pelo navegador usando o valor auto ou pelo script usando o valor manual.
• Usar variáveis de ambiente do CSS para receber informações sobre a aparência do teclado virtual, como keyboard-inset-height e keyboard-inset-top.

Leia mais sobre essa API em Controle total com a API VirtualKeyboard.

Recursos

• Como gerenciar várias telas com a API Window Management
• MDN: API Window Management
• Modo de aplicativo com guias para PWAs
• Ficar acordado com a API Screen Wake Lock
• Controle total com a API VirtualKeyboard
• Personalizar a sobreposição de controles da janela da barra de título do PWA
• Mostrar conteúdo na barra de título