Mostrar contenido en la barra de título

Un PWA puede definir cómo debe mostrarse en plataformas móviles, mediante la propiedad display en el archivo de manifiesto de la aplicación. Sin embargo, para crear una experiencia envolvente y nativa, las PWA de escritorio no pueden usar este enfoque.

De forma predeterminada, el área de la aplicación comienza inmediatamente debajo del área de la barra de título reservada:

Mostrar contenido donde normalmente está la barra de título puede ayudar a los PWA a sentirse más nativos. Muchas aplicaciones de escritorio, como Visual Studio Code, Microsoft Teams y Microsoft Edge ya lo hacen:

La API de superposición de controles de ventana hace lo siguiente:

• Te permite mostrar contenido web en toda la superficie de la aplicación.
• Mueve los controles críticos de ventana necesarios para el sistema a una superposición.
• Permite que el contenido no se superponga a esta superposición.

Habilitar la API de superposición de controles de ventana en Microsoft Edge

La API de superposición de controles de ventana es experimental y debe estar habilitada en Microsoft Edge, para usarla.

Para habilitar la API de superposición de controles de ventana:

1. En Microsoft Edge, vaya a edge://flags .

2. Seleccione Marcas de búsqueda y, a continuación, escriba "superposición de controles de ventana".

3. Seleccione Reinicio > habilitado > predeterminado.

   

La API de superposición de controles de ventana también está disponible como una característica de pruebas de origen. Para que los usuarios de la aplicación se beneficien de la superposición de controles de ventana sin tener que habilitarla en Microsoft Edge, puedes usar una prueba de origen.

Para obtener más información acerca de las pruebas de origen, vaya a Microsoft Edge Origin Trials Developer Console.

Habilitar la superposición de controles de ventana en la aplicación

Lo primero que debe hacer es habilitar la característica Superposición de controles de ventana en el archivo de manifiesto de aplicación web de la aplicación. Para ello, en el archivo de manifiesto, establezca la display_override propiedad:

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

Alternar la barra de título

Cuando la característica Superposición de controles de ventana está habilitada, el usuario puede elegir tener la barra de título o no, haciendo clic en el botón de alternancia de la barra de título:

El código no puede suponer que se muestra la superposición de controles de ventana, ya que:

• El usuario puede elegir si desea mostrar la barra de título.
• La aplicación también puede ejecutarse en un explorador web o en un dispositivo móvil, así como ejecutarse como una aplicación de escritorio.

Por lo tanto, el código debe reaccionar a los cambios en la geometría de la barra de título. Para obtener más información, vea React para superponer los cambios.

Usar variables de entorno CSS para mantenerse fuera de la superposición

La env() función CSS se puede usar para obtener acceso a las variables de entorno que define el agente de usuario.

La característica Superposición de controles de ventana agrega cuatro variables de entorno:

Puedes usar estas variables de entorno para colocar y cambiar el tamaño de la barra de título de la aplicación:

#title-bar {
    position: absolute;
    left: env(titlebar-area-x);
    top: env(titlebar-area-y);
    height: env(titlebar-area-height);
    width: env(titlebar-area-width);
}

Saber dónde está la superposición y qué tamaño es importante. Es posible que la superposición no siempre esté en el mismo lado de la ventana; en macOS, la superposición está en el lado izquierdo, pero en Windows, la superposición está en el lado derecho. Además, es posible que la superposición no siempre tenga el mismo tamaño.

Crear regiones de los controladores de arrastre de la aplicación para la ventana

Cuando la barra de título está oculta, solo permanecen visibles los controles de ventana críticos del sistema (los iconos Maximizar, Minimizar, Cerrar eInformación de la aplicación). Esto significa que hay muy poco espacio disponible para que los usuarios muevan la aplicación.

Puedes usar la propiedad -webkit-app-region CSS para ofrecer más formas de que los usuarios arrastren la aplicación. Por ejemplo, si la aplicación tiene su propia barra de título, puedes convertir su barra de título en un controlador de arrastre de ventana:

#title-bar {
    position: absolute;
    left: env(titlebar-area-x);
    top: env(titlebar-area-y);
    height: env(titlebar-area-height);
    width: env(titlebar-area-width);
    -webkit-app-region: drag;
}

React para superponer cambios

Un usuario puede alternar la barra de título o cambiar las dimensiones de la ventana mientras se ejecuta la aplicación. Saber cuándo suceden estas cosas puede ser importante para la aplicación. Es posible que la aplicación necesite reorganizar parte del contenido que se muestra en la barra de título o reorganizar el diseño en otra parte de la página.

Para escuchar los cambios, use el geometrychange evento. Para detectar si la barra de título está visible, use la visible propiedad del navigator.windowControlsOverlay objeto.

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.boundingRect;

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

Aplicación de demostración

Mis pistas es una PWA de demostración que usa la característica Superposición de controles de ventana.

1. En Microsoft Edge, habilite la superposición de controles de ventana.

2. Ve a Mis pistas e instala la aplicación.

3. Selecciona el botón Ocultar barra de título de la barra de título de la aplicación.

   Ahora, la aplicación muestra contenido hasta la parte superior del marco de la ventana, donde solía estar la barra de título. El área superior del mapa es un controlador de arrastre, para permitir que el usuario mueva la ventana.

   

El código fuente de esta aplicación está en el repositorio Mis pistas.

• El archivo de origen manifest.json declara el uso de la aplicación de la característica De superposición de controles de ventana.

• El overlay.js de origen usa el navigator.windowControlsOverlay objeto.

• El archivo de origen style.css usa la variable de entorno titlebar-area-height CSS.

Consulte también

• Tutorial de vídeo sobre superposición de controles de ventana
• Personalizar la superposición de controles de ventana de la barra de PWA la barra de título del usuario