Mostrar contenido en el área de la barra de título mediante la superposición de controles de ventana

Una aplicación web progresiva (PWA) instalada en el escritorio puede mostrar contenido donde normalmente está la barra de título, para que la PWA se sienta más nativa mediante la API de superposición de controles de ventana.

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

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

Una aplicación web progresiva (PWA) puede definir cómo debe mostrarse en plataformas móviles mediante el miembro de presentación en el archivo de manifiesto de la aplicación web. Sin embargo, para crear una experiencia inmersiva y nativa, los PWA de escritorio pueden usar otro enfoque.

De forma predeterminada, una PWA instalada en el escritorio puede mostrar contenido en un área que comienza inmediatamente debajo del área de la barra de título reservada:

Mostrar contenido donde la barra de título normalmente es puede ayudar a que las PWA se sientan más nativas. Muchas aplicaciones de escritorio, como Visual Studio Code, Microsoft Teams y Microsoft Edge ya lo hacen:

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

En primer lugar, habilite 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"]
}

Vea también:

• display_override en MDN.
• Uso de un manifiesto de aplicación web para integrar un PWA en el sistema operativo

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, porque:

• El usuario puede elegir si desea mostrar la barra de título.
• La aplicación también se puede ejecutar 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 de geometría de la barra de título. Para obtener más información, consulte React to overlay changes (Reaccionar a los cambios de superposición).

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

La env() función CSS se puede usar para acceder 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:

Variable	Descripción
titlebar-area-x	Distancia, en px, del área normalmente ocupada por la barra de título desde el lado izquierdo de la ventana
titlebar-area-y	Distancia, en px, del área normalmente ocupada por la barra de título desde el lado superior de la ventana
titlebar-area-width	Ancho del área de la barra de título, en px
titlebar-area-height	Alto del área de la barra de título, en px

Puede usar estas variables de entorno para colocar y ajustar el tamaño de su propio contenido donde normalmente aparecería la barra de título, cuando la característica de superposición de controles de ventana está deshabilitada:

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

El uso position: fixed; de garantiza que la barra de título no se desplaza con el resto del contenido y, en su lugar, permanece alineada con la superposición de controles de ventana.

Saber dónde es 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.

La env() función CSS toma un segundo parámetro útil para definir la posición del contenido de la aplicación cuando falta o deshabilita la característica de superposición de controles de ventana.

Convertir una región en un identificador de arrastre para la ventana

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

Puede usar la -webkit-app-region propiedad 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, puede convertir su barra de título en un identificador de arrastre de ventana:

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

Reacción a los cambios de superposición

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 tenga que reorganizar parte del contenido que se muestra en la barra de título o reorganizar el diseño en otro lugar de la página.

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

Tenga en cuenta que se geometrychange desencadena con mucha frecuencia cuando el usuario cambia el tamaño de la ventana. Para evitar ejecutar código que cambia el diseño con demasiada frecuencia y provocar problemas de rendimiento en la aplicación, usa una debounce función para limitar el número de veces que se controla el evento. Consulte La diferencia entre limitación y desenlazado.

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

Aplicación de demostración

1DIV es una aplicación de demostración de PWA que usa la característica Superposición de controles de ventana.

1. En Microsoft Edge, abra la aplicación de demostración de 1DIV en una nueva ventana o pestaña.

2. En la barra De direcciones, haga clic en la aplicación disponible. Instale 1DIV (). Se abre el cuadro de diálogo Instalar aplicación 1DIV .

3. Haga clic en el botón Instalar . La aplicación 1DIV se abre en su propia ventana, con el cuadro de diálogo Aplicación instalada abierta:

   

4. Haga clic en el botón Cerrar (X) del cuadro de diálogo. (O bien, active o desactive las casillas y, a continuación, haga clic en el botón Permitir ).

   La barra de título de la aplicación contiene al menos los siguientes controles de ventana:

   Icono	Información sobre herramientas
   	Ocultar barra de título
   	Configuración y mucho más
   	Minimize
   	Restaurar
   	Close

5. En la barra de título, haga clic en el botón Ocultar barra de título (

   La aplicación ahora muestra el contenido hasta la parte superior del marco de la ventana, donde la barra de título solía ser:

   

   El área superior de la aplicación es un identificador de arrastre para permitir que los usuarios muevan la ventana.

El código fuente de esta aplicación de demostración está en el repositorio 1DIV .

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

• El archivo de origenapp.js usa el navigator.windowControlsOverlay objeto .

• El archivo de origen app.css usa las variables de titlebar-area-* entorno CSS.

Vista previa de la superposición personalizada sin instalar el PWA

En Microsoft Edge DevTools, en la herramienta Aplicación , puede simular la característica Superposición de controles de ventana (WCO), sin tener que instalar primero la PWA y habilitar la característica WCO. Al simular la característica WCO desde DevTools, puede probar los cambios de código CSS para el área de la barra de título más rápidamente que reinstalando la PWA revisada.

La superposición simulada es una imagen estática. Los valores de las variables env(titlebar-area-left)CSS , , env(titlebar-area-width)env(titlebar-area-top)y env(titlebar-area-height) se establecen para que coincidan con la plataforma que seleccione.

Consulte Simulación de la API de superposición de controles de ventana sin instalar el PWA.

Vea también

• Simula la API de superposición de controles de ventana sin instalar la característica PWA - DevTools.
• Tutorial de vídeo superposición de controles de ventana
• Personalización de la superposición de controles de ventana de la barra de título de la PWA
• Salir de la caja
• display_override en MDN.