Anzeigen von Inhalten im Titelleistenbereich mithilfe der Überlagerung von Fenstersteuerelementen

Eine progressive Web-App (PWA), die auf dem Desktop installiert ist, kann Mithilfe der Überlagerungs-API für Fenstersteuerelemente Inhalte an der Stelle anzeigen, an der sich die Titelleiste normalerweise befindet, damit sich die PWA nativ anfühlt.

Die Überlagerungs-API für Fenstersteuerelemente führt folgende Aktionen aus:

• Ermöglicht die Anzeige von Webinhalten über die gesamte Oberfläche der App.
• Verschiebt die kritischen, vom System erforderlichen Fenstersteuerelemente in eine Überlagerung.
• Ermöglicht es Ihren Inhalten, von dieser Überlagerung fern zu bleiben.

Eine progressive Web-App (PWA) kann definieren, wie sie auf mobilen Plattformen angezeigt werden soll, indem sie das Anzeigeelement in der Web-App-Manifestdatei verwendet. Um jedoch eine immersive, native Erfahrung zu schaffen, können Desktop-PWAs einen anderen Ansatz verwenden.

Standardmäßig kann eine auf dem Desktop installierte PWA Inhalte in einem Bereich anzeigen, der unmittelbar unterhalb des reservierten Titelleistenbereichs beginnt:

Das Anzeigen von Inhalten, in denen die Titelleiste normalerweise ist, kann dazu beitragen, dass PWAs nativer wirken. Viele Desktopanwendungen wie Visual Studio Code, Microsoft Teams und Microsoft Edge tun dies bereits:

Aktivieren der Fenstersteuerelementüberlagerung in Ihrer App

Aktivieren Sie zunächst das Feature "Fenstersteuerelementüberlagerung" in der Web-App-Manifestdatei Ihrer App. Legen Sie hierzu in der Manifestdatei die display_override -Eigenschaft fest:

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

Siehe auch:

• display_override bei MDN.
• Verwenden eines Web-App-Manifests zum Integrieren einer PWA in das Betriebssystem

Titelleiste umschalten

Wenn das Feature Überlagerung von Fenstersteuerelementen aktiviert ist, kann der Benutzer die Titelleiste auswählen oder nicht, indem er auf die Umschaltfläche der Titelleiste klickt:

Ihr Code kann nicht davon ausgehen, dass die Überlagerung der Fenstersteuerelemente angezeigt wird, weil:

• Der Benutzer kann auswählen, ob die Titelleiste angezeigt werden soll.
• Ihre App kann auch in einem Webbrowser oder auf einem mobilen Gerät sowie als Desktop-App ausgeführt werden.

Daher muss Ihr Code auf Änderungen der Titelleistengeometrie reagieren. Weitere Informationen finden Sie unter Reagieren auf Überlagerungsänderungen.

Verwenden von CSS-Umgebungsvariablen, um die Überlagerung nicht zu kennen

Die env() CSS-Funktion kann für den Zugriff auf Umgebungsvariablen verwendet werden, die vom Benutzer-Agent definiert werden.

Vier Umgebungsvariablen werden vom Feature "Fenstersteuerelementüberlagerung" hinzugefügt:

Variable	Beschreibung
titlebar-area-x	Abstand in pxdes Bereichs, der normalerweise von der Titelleiste belegt wird, von der linken Seite des Fensters
titlebar-area-y	Abstand in pxdes Bereichs, der normalerweise von der Titelleiste belegt wird, von der oberen Seite des Fensters
titlebar-area-width	Breite des Titelleistenbereichs, in px
titlebar-area-height	Höhe des Titelleistenbereichs, in px

Sie können diese Umgebungsvariablen verwenden, um Ihre eigenen Inhalte an der Stelle zu positionieren und zu dimensionieren, an der die Titelleiste normalerweise angezeigt wird, wenn die Überlagerungsfunktion für Fenstersteuerelemente deaktiviert ist:

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

Wenn Sie verwenden, position: fixed; wird sichergestellt, dass die Titelleiste nicht mit dem restlichen Inhalt scrollt und stattdessen an der Überlagerung der Fenstersteuerelemente ausgerichtet bleibt.

Es ist wichtig zu wissen, wo sich die Überlagerung befindet und wie groß sie ist. Die Überlagerung befindet sich möglicherweise nicht immer auf derselben Seite des Fensters. Unter macOS befindet sich die Überlagerung auf der linken Seite, unter Windows befindet sich die Überlagerung auf der rechten Seite. Außerdem hat die Überlagerung möglicherweise nicht immer die gleiche Größe.

Die env() CSS-Funktion verwendet einen zweiten Parameter, der nützlich ist, um die Position Ihres App-Inhalts zu definieren, wenn die Überlagerungsfunktion für Fenstersteuerelemente fehlt oder deaktiviert ist.

Festlegen eines Bereichs als Ziehpunkt für das Fenster

Wenn die Titelleiste ausgeblendet ist, bleiben nur die systemkritischen Fenstersteuerelemente sichtbar (die Symbole Maximieren, Minimieren, Schließen und App-Info ). Dies bedeutet, dass nur sehr wenig Platz für Benutzer verfügbar ist, um das Anwendungsfenster zu verschieben.

Sie können die CSS-Eigenschaft -webkit-app-region verwenden, um Benutzern weitere Möglichkeiten zum Ziehen der App zu bieten. Wenn Ihre App beispielsweise über eine eigene Titelleiste verfügt, können Sie die Titelleiste in einen Fensterziehpunkt umwandeln:

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

Reagieren auf Überlagerungsänderungen

Ein Benutzer kann die Titelleiste umschalten oder die Fensterdimensionen ändern, während die App ausgeführt wird. Zu wissen, wann diese Dinge passieren, kann für Ihre App wichtig sein. Ihre App muss möglicherweise einen Teil der Inhalte neu anordnen, die in der Titelleiste angezeigt werden, oder das Layout an einer anderen Stelle auf der Seite neu anordnen.

Um auf Änderungen zu lauschen, verwenden Sie das geometrychange -Ereignis für das navigator.windowControlsOverlay -Objekt. Um zu ermitteln, ob die Titelleiste sichtbar ist, verwenden Sie die visible -Eigenschaft für das navigator.windowControlsOverlay -Objekt.

Beachten Sie, dass sehr geometrychange häufig ausgelöst wird, wenn der Benutzer die Größe des Fensters ändert. Um zu vermeiden, dass Layoutcode zu häufig ausgeführt wird und Leistungsprobleme in Ihrer App verursacht werden, verwenden Sie eine debounce Funktion, um zu begrenzen, wie oft das Ereignis behandelt wird. Weitere Informationen finden Sie unter Der Unterschied zwischen Drosselung und 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));
}

Demo-App

1DIV ist eine PWA-Demo-App, die das Feature "Fenstersteuerelementüberlagerung" verwendet.

1. Öffnen Sie in Microsoft Edge die 1DIV-Demo-App in einem neuen Fenster oder einer neuen Registerkarte.

2. Klicken Sie in der Adressleiste auf die verfügbare App. Installieren Sie 1DIV () Schaltfläche. Das Dialogfeld 1DIV-App installieren wird geöffnet.

3. Klicken Sie auf die Schaltfläche Installieren . Die 1DIV-App wird in einem eigenen Fenster geöffnet, in dem das Dialogfeld App installiert geöffnet ist:

   

4. Klicken Sie auf die Schaltfläche Schließen (X) des Dialogfelds. (Oder aktivieren oder deaktivieren Sie die Kontrollkästchen, und klicken Sie dann auf die Schaltfläche Zulassen .)

   Die Titelleiste der App enthält mindestens die folgenden Fenstersteuerelemente:

   Symbol	Tooltip
   	Titelleiste ausblenden
   	Einstellungen und mehr
   	Minimize
   	Wiederherstellen
   	Close

5. Klicken Sie in der Titelleiste auf die Schaltfläche Titelleiste ausblenden (

   Die App zeigt jetzt Inhalte bis zum oberen Rand des Fensterrahmens an, wo sich die Titelleiste früher wie folgt gezeigt hat:

   

   Der obere Bereich der App ist ein Ziehpunkt, mit dem Benutzer das Fenster verschieben können.

Der Quellcode für diese Demo-App befindet sich im 1DIV-Repository .

• Die manifest.json Quelldatei deklariert die Verwendung des Features "Fenstersteuerelementüberlagerung" durch die App.

• Die app.js Quelldatei verwendet das navigator.windowControlsOverlay -Objekt.

• Die app.css Quelldatei verwendet die titlebar-area-* CSS-Umgebungsvariablen.

Vorschau der benutzerdefinierten Überlagerung ohne Installation der PWA

In Microsoft Edge DevTools können Sie im Anwendungstool das Feature Window Controls Overlay (WCO) simulieren, ohne zuerst die PWA installieren und das WCO-Feature aktivieren zu müssen. Durch die Simulation des WCO-Features in DevTools können Sie CSS-Codeänderungen für Ihren Titelleistenbereich schneller testen als durch erneutes Installieren des überarbeiteten PWA.

Die simulierte Überlagerung ist ein statisches Bild. Die Werte der CSS-Variablen env(titlebar-area-left), env(titlebar-area-top), env(titlebar-area-width)und env(titlebar-area-height) werden so festgelegt, dass sie der ausgewählten Plattform entsprechen.

Weitere Informationen finden Sie unter Simulieren der Überlagerungs-API für Fenstersteuerelemente, ohne PWA zu installieren.

Siehe auch

• Simulieren Sie die Überlagerungs-API für Fenstersteuerelemente, ohne ihr PWA DevTools-Feature zu installieren.
• Videotutorial zur Überlagerung von Fenstersteuerelementen
• Anpassen der Fenstersteuerelementüberlagerung der Titelleiste Ihrer PWA
• Out-of-the-Box-Ausbrechen
• display_override bei MDN.