Afficher le contenu dans la zone de la barre de titre à l’aide de la superposition de contrôles de fenêtre

Une application web progressive (PWA) installée sur le bureau peut afficher du contenu là où se trouve normalement la barre de titre, pour rendre la PWA plus native, à l’aide de l’API de superposition de contrôles de fenêtre.

L’API de superposition de contrôles de fenêtre effectue les opérations suivantes :

  • Permet d’afficher du contenu web sur toute la surface de l’application.
  • Déplace les contrôles de fenêtre critiques requis par le système dans une superposition.
  • Permet à votre contenu de rester à l’écart de cette superposition.

Une application web progressive (PWA) peut définir la façon dont elle doit être affichée sur les plateformes mobiles, en utilisant le membre d’affichage dans le fichier manifeste de l’application web. Toutefois, pour créer une expérience immersive de type natif, les PWA de bureau peuvent utiliser une autre approche.

Par défaut, un PWA installé sur le bureau peut afficher du contenu dans une zone qui commence immédiatement sous la zone de la barre de titre réservée :

Une application PWA sur Windows montrant que le contenu de l’application est affiché sous la zone de la barre de titre réservée

L’affichage du contenu à l’endroit où se trouve normalement la barre de titre peut aider les PWA à se sentir plus natifs. De nombreuses applications de bureau, telles que Visual Studio Code, Microsoft Teams et Microsoft Edge, le font déjà :

Visual Studio Code affiche le contenu dans la zone de la barre de titre

Activer la superposition des contrôles de fenêtre dans votre application

Tout d’abord, activez la fonctionnalité Superposition des contrôles de fenêtre dans le fichier manifeste de l’application web de votre application. Pour ce faire, dans le fichier manifeste, définissez la display_override propriété :

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

Voir aussi :

Utiliser des variables d’environnement CSS pour éviter la superposition

La env() fonction CSS peut être utilisée pour accéder aux variables d’environnement définies par l’agent utilisateur.

Quatre variables d’environnement sont ajoutées par la fonctionnalité de superposition des contrôles de fenêtre :

Variable Description
titlebar-area-x Distance, en px, de la zone normalement occupée par la barre de titre à partir du côté gauche de la fenêtre.
titlebar-area-y Distance, en px, de la zone normalement occupée par la barre de titre à partir du côté supérieur de la fenêtre.
titlebar-area-width Largeur de la zone de la barre de titre, en px.
titlebar-area-height Hauteur de la zone de la barre de titre, en px.

Vous pouvez utiliser ces variables d’environnement pour positionner et dimensionner votre propre contenu là où la barre de titre apparaîtrait normalement, lorsque la fonctionnalité de superposition des contrôles de fenêtre est désactivée :

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

L’utilisation position: fixed; de permet de s’assurer que votre barre de titre ne défile pas avec le reste du contenu et reste alignée sur la superposition des contrôles de fenêtre.

Il est important de savoir où se trouve la superposition et quelle est sa taille. La superposition n’est peut-être pas toujours du même côté de la fenêtre ; sur macOS, la superposition se trouve sur le côté gauche, mais sur Windows, elle se trouve sur le côté droit. De plus, la superposition peut ne pas toujours être de la même taille.

La env() fonction CSS prend un deuxième paramètre utile pour définir la position du contenu de votre application lorsque la fonctionnalité de superposition de contrôles de fenêtre est manquante ou désactivée.

Faire d’une région une poignée de déplacement pour la fenêtre

Lorsque la barre de titre est masquée, seuls les contrôles de fenêtre critiques pour le système restent visibles (les icônes Agrandir, Réduire, Fermer et Informations sur l’application ). Cela signifie que les utilisateurs disposent de très peu d’espace pour déplacer la fenêtre de l’application.

Vous pouvez utiliser la app-region propriété CSS pour offrir aux utilisateurs d’autres moyens de faire glisser l’application. Par exemple, si votre application possède sa propre barre de titre, vous pouvez transformer celle-ci en poignée de déplacement pour fenêtre :

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

Réagir aux changements de superposition

Un utilisateur peut basculer la barre de titre ou modifier les dimensions de la fenêtre pendant l’exécution de l’application. Il peut être important pour votre application de savoir quand ces événements se produisent. Votre application devra peut-être réorganiser une partie du contenu affiché dans la barre de titre ou réorganiser la disposition ailleurs sur la page.

Pour écouter les modifications, utilisez l’événement geometrychange sur l’objet navigator.windowControlsOverlay . Pour détecter si la barre de titre est visible, utilisez la visible propriété sur l’objet navigator.windowControlsOverlay .

L’événement geometrychange est déclenché très fréquemment lorsque l’utilisateur redimensionne la fenêtre. Pour éviter d’exécuter trop souvent du code modifiant la disposition et de provoquer des problèmes de performances dans votre application, utilisez une debounce fonction pour limiter le nombre de fois où l’événement est géré. Voir la différence entre la limitation et le rebond.

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

Demo app

1DIV est une application de démonstration PWA qui utilise la fonction de superposition des contrôles de fenêtre.

  1. Dans Microsoft Edge, ouvrez l’application de démonstration 1DIV dans une nouvelle fenêtre ou un nouvel onglet.

  2. Dans la barre d’adresses, cliquez sur l’application disponible. Install 1DIV (The ). La boîte de dialogue Installer l’application 1DIV s’ouvre.

  3. Cliquez sur le bouton Installer . L’application 1DIV s’ouvre dans sa propre fenêtre, avec la boîte de dialogue installée de l’application ouverte :

    L’application 1DIV dans sa propre fenêtre, affichant la boîte de dialogue « Application installée »

  4. Cliquez sur le bouton Fermer (X) de la boîte de dialogue. (Vous pouvez également cocher ou décocher des cases, puis cliquer sur le bouton Autoriser .)

    La barre de titre de l’application contient au moins les contrôles de fenêtre suivants :

    Icône Info-bulle
    L’icône « Paramètres et plus » Paramètres et bien plus encore
    Icône « Réduire » Minimize
    L’icône « Restaurer » Restaurer
    Icône « Fermer » Close

    L’application affiche désormais le contenu jusqu’en haut du cadre de la fenêtre, là où se trouvait la barre de titre :

    La zone supérieure de la carte peut être utilisée pour déplacer la fenêtre

    La zone supérieure de l’application est une poignée de glissement, pour permettre aux utilisateurs de déplacer la fenêtre.

Le code source de cette application de démonstration se trouve dans le référentiel 1DIV .

  • Le fichier source manifest.json déclare l’utilisation par l’application de la fonctionnalité de superposition des contrôles de fenêtre.

  • Le fichier sourceapp.js utilise l’objet navigator.windowControlsOverlay .

  • Le fichier source app.css utilise les variables d’environnement titlebar-area-* CSS.

Affichez un aperçu de la superposition personnalisée sans installer le PWA

Dans Microsoft Edge DevTools, dans l’outil Application , vous pouvez simuler la fonctionnalité de superposition de contrôles de fenêtre (WCO), sans devoir installer au préalable la fonctionnalité PWA et activer la fonctionnalité WCO. En simulant la fonctionnalité WCO à partir de DevTools, vous pouvez tester les modifications de code CSS pour votre zone de barre de titre plus rapidement qu’en réinstallant la PWA révisée.

La superposition simulée est une image statique. Les valeurs des variables env(titlebar-area-left)CSS , env(titlebar-area-top), env(titlebar-area-width), et env(titlebar-area-height) sont définies pour correspondre à la plateforme que vous sélectionnez.

Consultez Simuler l’API de superposition des contrôles de fenêtre sans installer votre PWA.

Voir aussi

MDN :

Blogue :

YouTube :

Démo :

  • Last updated on