Apresentar conteúdo na área da barra de título com a Sobreposição de Controlos de Janela

Artigo
07/16/2024

Uma Aplicação Web Progressiva (PWA) instalada no ambiente de trabalho pode apresentar conteúdo onde a barra de título é normalmente, para tornar o PWA mais nativo, utilizando a API de Sobreposição de Controlos de Janela.

A API de Sobreposição de Controlos de Janela faz o seguinte:

Permite-lhe apresentar conteúdo Web em toda a área da superfície da aplicação.
Move os controlos de janela necessários para o sistema críticos para uma sobreposição.
Permite que os seus conteúdos se mantenham afastados desta sobreposição.

Uma Aplicação Web Progressiva (PWA) pode definir como deve ser apresentada nas plataformas móveis, utilizando o membro de apresentação no ficheiro de manifesto da aplicação Web. No entanto, para criar uma experiência envolvente e nativa, os PWAs de ambiente de trabalho podem utilizar outra abordagem.

Por predefinição, um PWA instalado no ambiente de trabalho pode apresentar conteúdo numa área que começa imediatamente abaixo da área da barra de título reservada:

Uma aplicação PWA no Windows a mostrar que o conteúdo da aplicação é apresentado abaixo da área da barra de título reservada

Apresentar conteúdo onde a barra de título é normalmente pode ajudar os PWAs a sentirem-se mais nativos. Muitas aplicações de ambiente de trabalho, como o Visual Studio Code, o Microsoft Teams e o Microsoft Edge, já o fazem:

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

Ativar a Sobreposição de Controlos de Janela na sua aplicação

Em primeiro lugar, ative a funcionalidade Sobreposição de Controlos de Janela no ficheiro de manifesto da aplicação Web da sua aplicação. Para tal, no ficheiro de manifesto, defina a display_override propriedade:

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

Veja também:

Ativar/desativar a barra de título

Quando a funcionalidade Sobreposição de Controlos de Janela está ativada, o utilizador pode optar por ter ou não a barra de título ao clicar no botão de alternar da barra de título:

O código não pode assumir que a sobreposição dos controlos de janela é apresentada porque:

O utilizador pode escolher se pretende apresentar a barra de título.
A sua aplicação também pode ser executada num browser ou num dispositivo móvel, bem como em execução como uma aplicação de ambiente de trabalho.

Por conseguinte, o código tem de reagir às alterações de geometria da barra de título. Para saber mais, veja Reagir à sobreposição de alterações.

Utilizar variáveis de ambiente CSS para se manter afastado da sobreposição

A env() função CSS pode ser utilizada para aceder às variáveis de ambiente que o agente de utilizador define.

São adicionadas quatro variáveis de ambiente pela funcionalidade Sobreposição de Controlos de Janela:

Variável	Descrição
`titlebar-area-x`	Distância, em `px`, da área normalmente ocupada pela barra de título do lado esquerdo da janela
`titlebar-area-y`	Distância, em `px`, da área normalmente ocupada pela barra de título do lado superior da janela
`titlebar-area-width`	Largura da área da barra de título, em `px`
`titlebar-area-height`	Altura da área da barra de título, em `px`

Pode utilizar estas variáveis de ambiente para posicionar e dimensionar os seus próprios conteúdos onde a barra de título é normalmente apresentada, quando a funcionalidade de sobreposição dos controlos de janela está desativada:

#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%);
}

Utilizar position: fixed; garante que a barra de título não se desloca com o resto do conteúdo e, em vez disso, permanece alinhada com a sobreposição dos controlos de janela.

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

A env() função CSS utiliza um segundo parâmetro útil para definir a posição do conteúdo da aplicação quando a funcionalidade de sobreposição dos controlos de janela está em falta ou desativada.

Tornar uma região numa alça de arrastar para a janela

Quando a barra de título está oculta, apenas os controlos de janela críticos do sistema permanecem visíveis (os ícones Maximizar, Minimizar, Fechar e Informações da Aplicação ). Isto significa que há muito pouco espaço disponível para os utilizadores moverem a janela da aplicação.

Pode utilizar a -webkit-app-region propriedade CSS para oferecer mais formas de os utilizadores arrastarem a aplicação. Por exemplo, se a sua aplicação tiver a sua própria barra de título, pode transformar a barra de título numa alça de arrastar 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%);
  -webkit-app-region: drag;
}

Reagir a alterações de sobreposição

Um utilizador pode alternar a barra de título ou alterar as dimensões da janela enquanto a aplicação está em execução. Saber quando estas coisas acontecem pode ser importante para a sua aplicação. A sua aplicação poderá ter de reorganizar alguns dos conteúdos apresentados na barra de título ou reorganizar o esquema noutro local da página.

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

Tenha em atenção que o geometrychange é acionado com muita frequência quando o utilizador redimensiona a janela. Para evitar a execução de código de alteração de esquema com demasiada frequência e causar problemas de desempenho na sua aplicação, utilize uma debounce função para limitar o número de vezes que o evento é processado. 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));
}

Aplicação de demonstração

1DIV é uma aplicação de demonstração do PWA que utiliza a funcionalidade Sobreposição de Controlos de Janela.

No Microsoft Edge, abra a aplicação de demonstração 1DIV numa nova janela ou separador.
Na Barra de endereço, clique na Aplicação disponível. Instale o 1DIV ("). É aberta a caixa de diálogo Instalar aplicação 1DIV .
Clique no botão Instalar . A aplicação 1DIV é aberta na sua própria janela, com a caixa de diálogo Aplicação instalada aberta:

Clique no botão Fechar (X) da caixa de diálogo. (Em alternativa, selecione ou desmarque caixas de verificação e, em seguida, clique no botão Permitir .)

A barra de título da aplicação contém, pelo menos, os seguintes controlos de janela:

Ícone	Dica de ferramenta
	Ocultar barra de título
	Definições e muito mais
	Minimize
	Restaurar
	Close

Na barra de título, clique no botão Ocultar barra de título (").

A aplicação apresenta agora conteúdo até à parte superior da moldura da janela, onde costumava estar a barra de título:

A área superior da aplicação é uma alça de arrastar, para permitir que os utilizadores movam a janela.

O código fonte desta aplicação de demonstração está no repositório 1DIV .

O manifest.json ficheiro de origem declara a utilização da aplicação da funcionalidade Sobreposição de Controlos de Janela.
O app.js ficheiro de origem utiliza o navigator.windowControlsOverlay objeto .
O app.css ficheiro de origem utiliza as titlebar-area-* variáveis de ambiente CSS.

Pré-visualizar a sobreposição personalizada sem instalar o PWA

No Microsoft Edge DevTools, na ferramenta Aplicação , pode simular a funcionalidade Sobreposição de Controlos de Janela (WCO), sem ter de instalar primeiro o PWA e ativar a funcionalidade WCO. Ao simular a funcionalidade WCO a partir de DevTools, pode testar as alterações de código CSS para a área da barra de título mais rapidamente do que reinstalando o PWA revisto.

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) estão definidos para corresponder à plataforma que selecionar.

Veja Simular a API de Sobreposição de Controlos de Janela sem instalar o PWA.

Compartilhar via