Exibir conteúdo na barra de título
Um PWA 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, as PWAs da área de trabalho 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 reservada da barra de título:
Exibir conteúdo em que a barra de título normalmente é pode ajudar as PWAs a se sentirem mais nativas. Muitos aplicativos de área de trabalho, como Visual Studio Code, Microsoft Teams e Microsoft Edge já fazem isso:
A API de Sobreposição de Controles de Janela faz o seguinte:
- Permite exibir conteúdo da Web em toda a área de superfície do aplicativo.
- Move os controles críticos de janela exigidos pelo sistema para uma sobreposição.
- Torna possível que seu conteúdo fique longe dessa sobreposição.
Habilitar a sobreposição controles de janela em seu aplicativo
A primeira coisa a fazer é habilitar o recurso Sobreposição de Controles de Janela no arquivo manifesto do aplicativo Web App. Para fazer isso, no arquivo de manifesto, defina a display_override propriedade:
{
"display_override": ["window-controls-overlay"]
}
Alternar a barra de título
Quando o recurso Sobreposição controles de janela está habilitado, o usuário pode optar por ter a barra de título ou não, clicando no botão alternar barra de título:
Seu código não pode assumir que a sobreposição de controles de janela seja exibida, pois:
- O usuário pode escolher se deve exibir a barra de título.
- Seu aplicativo também pode ser executado em um navegador da Web ou em um dispositivo móvel, bem como em execução como um aplicativo de área de trabalho.
Portanto, seu código precisa reagir às alterações de geometria da barra de título. Para saber mais, confira React sobreposição de alterações.
Usar variáveis de ambiente CSS para ficar longe da sobreposição
A env() função CSS pode ser usada para acessar variáveis de ambiente definidas pelo agente de 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 |
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 |
Você pode usar essas variáveis de ambiente para posicionar e dimensionar seu próprio conteúdo em que a barra de título normalmente seria exibida, quando o recurso de sobreposição controles de janela estiver 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, em vez disso, permaneça alinhada com a sobreposição de controles de janela.
Saber onde a sobreposição é e o tamanho dela é importante. A sobreposição pode nem sempre estar no mesmo lado da janela; no macOS, a sobreposição fica no lado esquerdo, mas no Windows, a sobreposição está no lado direito. Além disso, a sobreposição pode nem sempre ter 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 controles de janela está ausente ou desabilitado.
Fazer regiões do seu aplicativo arrastar manipuladores para a janela
Quando a barra de título está oculta, apenas 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 -webkit-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 um manipulador de arrastar janelas:
#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;
}
React sobreposição de 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 ouvir as alterações, use o geometrychange evento no navigator.windowControlsOverlay objeto. Para detectar se a barra de título está visível, use a visible propriedade no navigator.windowControlsOverlay objeto.
Observe que o geometrychange é disparado com muita frequência quando o usuário redimensiona a janela. Para evitar executar o código de alteração de layout com muita frequência e causar problemas de desempenho em seu aplicativo, use uma debounce função para limitar quantas vezes o evento é tratado. Consulte 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 PWA que usa o recurso Sobreposição controles de janela.
No Microsoft Edge, acesse 1DIV e instale o aplicativo.
Clique em Ocultar barra de título na barra de título do aplicativo.
O aplicativo agora exibe conteúdo até a parte superior do quadro da janela, onde a barra de título costumava estar. A área superior do aplicativo é um manipulador 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 .
O arquivo de origem manifest.json declara o uso do aplicativo do recurso sobreposição controles de janela.
O arquivo de origemapp.jsusa o
navigator.windowControlsOverlayobjeto.O arquivo de origem app.css usa as variáveis de
titlebar-area-*ambiente CSS.