Exibir conteúdo na área da barra de título usando a sobreposição de controles de janela

Um PWA (Aplicativo Web Progressivo) instalado na área de trabalho pode exibir conteúdo onde a barra de título normalmente está, para fazer o PWA parecer mais nativo, usando a API de Sobreposição de Controles de Janela.

A API de sobreposição de controles de janela faz o seguinte:

  • Permite exibir conteúdo da Web em toda a área da superfície do aplicativo.
  • Move os controles de janela críticos exigidos pelo sistema para uma sobreposição.
  • Possibilita que seu conteúdo fique longe dessa sobreposição.

Um PWA (Aplicativo Web Progressivo) pode definir como ele deve ser exibido em plataformas móveis, usando o membro de exibição no arquivo de manifesto do aplicativo Web. No entanto, para criar uma experiência imersiva e nativa, os PWAs de desktop podem usar outra abordagem.

Por padrão, um PWA instalado na área de trabalho pode exibir conteúdo em uma área que começa imediatamente abaixo da área da barra de título reservada:

Um aplicativo PWA no Windows mostrando que o conteúdo do aplicativo é exibido abaixo da área da barra de título reservada

Exibir conteúdo onde a barra de título normalmente está pode ajudar os PWAs a se sentirem mais nativos. Muitos aplicativos da área de trabalho, como o Visual Studio Code, o Microsoft Teams e o Microsoft Edge, já fazem isso:

O Visual Studio Code exibe conteúdo na área da barra de título

Habilitar a sobreposição de controles de janela em seu aplicativo

Primeiro, habilite o recurso Sobreposição de Controles de Janela no arquivo de manifesto do aplicativo Web do seu aplicativo. Para fazer isso, no arquivo de manifesto, defina a display_override propriedade:

{
  "display_override": ["window-controls-overlay"]
}

Veja também:

Use variáveis de ambiente CSS para evitar a sobreposição

A env() função CSS pode ser usada para acessar variáveis de ambiente definidas pelo agente do usuário.

Quatro variáveis de ambiente são adicionadas pelo recurso Sobreposição de Controles de Janela:

Variável Descrição
titlebar-area-x A distância, em px, da área normalmente ocupada pela barra de título do lado esquerdo da janela.
titlebar-area-y A distância, em px, da área normalmente ocupada pela barra de título a partir do lado superior da janela.
titlebar-area-width A largura da área da barra de título, em px.
titlebar-area-height A altura da área da barra de título, em px.

Você pode usar essas variáveis de ambiente para posicionar e dimensionar seu próprio conteúdo onde a barra de título normalmente apareceria, quando o recurso de sobreposição de controles de janela está desabilitado:

#title-bar {
  position: fixed;
  left: env(titlebar-area-x, 0);
  top: env(titlebar-area-y, 0);
  height: env(titlebar-area-height, 50px);
  width: env(titlebar-area-width, 100%);
}

O uso position: fixed; garante que a barra de título não role com o restante do conteúdo e permaneça alinhada com a sobreposição dos controles da janela.

Saber onde está a sobreposição e quão grande ela é é importante. A sobreposição pode nem sempre estar do mesmo lado da janela; no macOS, a sobreposição fica no lado esquerdo, mas no Windows, a sobreposição fica no lado direito. Além disso, a sobreposição pode não ter sempre o mesmo tamanho.

A env() função CSS usa um segundo parâmetro que é útil para definir a posição do conteúdo do aplicativo quando o recurso de sobreposição de controles de janela está ausente ou desabilitado.

Fazer de uma região uma alça de arrastar para a janela

Quando a barra de título está oculta, somente os controles de janela críticos do sistema permanecem visíveis (os ícones Maximizar, Minimizar, Fechar e Informações do Aplicativo ). Isso significa que há muito pouco espaço disponível para os usuários moverem a janela do aplicativo.

Você pode usar a app-region propriedade CSS para oferecer mais maneiras para os usuários arrastarem o aplicativo. Por exemplo, se seu aplicativo tiver sua própria barra de título, você poderá transformar sua barra de título em uma alça de arrastar da janela:

#title-bar {
  position: fixed;
  left: env(titlebar-area-x, 0);
  top: env(titlebar-area-y, 0);
  height: env(titlebar-area-height, 50px);
  width: env(titlebar-area-width, 100%);
  app-region: drag;
}

React para sobrepor alterações

Um usuário pode alternar a barra de título ou alterar as dimensões da janela enquanto o aplicativo está em execução. Saber quando essas coisas acontecem pode ser importante para seu aplicativo. Seu aplicativo pode precisar reorganizar parte do conteúdo exibido na barra de título ou reorganizar o layout em outro lugar da página.

Para escutar as alterações, use o geometrychange evento no navigator.windowControlsOverlay objeto. Para detectar se a barra de título está visível, use a visiblenavigator.windowControlsOverlay propriedade no objeto.

O geometrychange evento é acionado com muita frequência quando o usuário redimensiona a janela. Para evitar a execução de código que altera o layout com muita frequência e causa problemas de desempenho no aplicativo, use uma debounce função para limitar quantas vezes o evento é manipulado. Veja a diferença entre limitação e debouncing.

const debounce = (func, wait) => {
  let timeout;
  return function executedFunction(...args) {
    const later = () => {
      clearTimeout(timeout);
      func(...args);
    };
    clearTimeout(timeout);
    timeout = setTimeout(later, wait);
  };
};

if ('windowControlsOverlay' in navigator) {
  navigator.windowControlsOverlay.addEventListener('geometrychange', debounce(e => {
    // Detect if the Window Controls Overlay is visible.
    const isOverlayVisible = navigator.windowControlsOverlay.visible;

    // Get the size and position of the title bar area.
    const titleBarRect = e.titlebarAreaRect;

    console.log(`The overlay is ${isOverlayVisible ? 'visible' : 'hidden'}, the title bar width is ${titleBarRect.width}px`);
  }, 200));
}

Aplicativo de demonstração

1DIV é um aplicativo de demonstração do PWA que usa o recurso Sobreposição de Controles de Janela.

  1. No Microsoft Edge, abra o aplicativo de demonstração 1DIV em uma nova janela ou guia.

  2. Na barra de endereços, clique no aplicativo disponível. Instale o 1DIV (O aplicativo ). A caixa de diálogo Instalar aplicativo 1DIV é aberta.

  3. Clique no botão Instalar . O aplicativo 1DIV é aberto em sua própria janela, com a caixa de diálogo Aplicativo instalado aberta:

    O aplicativo 1DIV em sua própria janela, exibindo a caixa de diálogo

  4. Clique no botão Fechar (X) da caixa de diálogo. (Ou marque ou desmarque as caixas de seleção e clique no botão Permitir .)

    A barra de título do aplicativo contém pelo menos os seguintes controles de janela:

    Ícone Dica de ferramenta
    O ícone Configurações e mais
    O ícone Minimize
    O ícone Restaurar
    O ícone Close

    O aplicativo agora exibe o conteúdo até a parte superior do quadro da janela, onde a barra de título costumava estar:

    A área superior do mapa pode ser usada para mover a janela

    A área superior do aplicativo é uma alça de arrastar para permitir que os usuários movam a janela.

O código-fonte deste aplicativo de demonstração está no repositório 1DIV .

Visualizar a sobreposição personalizada sem instalar o PWA

No Microsoft Edge DevTools, na ferramenta Aplicativo , você pode simular o recurso Sobreposição de Controles de Janela (WCO), sem precisar instalar o PWA primeiro e habilitar o recurso WO. Simulando o recurso WCO no DevTools, você pode testar alterações de código CSS para a área da barra de título mais rapidamente do que reinstalando o PWA revisado.

A sobreposição simulada é uma imagem estática. Os valores das variáveis env(titlebar-area-left)CSS , env(titlebar-area-top), env(titlebar-area-width), e env(titlebar-area-height) são definidos para corresponder à plataforma selecionada.

Consulte Simular a API de sobreposição de controles de janela sem instalar o PWA.

Confira também

MDN:

Blog:

YouTube:

Demonstração:

  • Last updated on