Anzeigen von Inhalten im Titelleistenbereich mithilfe der Überlagerung von Fenstersteuerelementen

Eine auf dem Desktop installierte Progressive Web App (PWA) kann Inhalte dort anzeigen, wo sich normalerweise die Titelleiste befindet, damit sich die PWA mithilfe der Überlagerungs-API für Fenstersteuerelemente nativer anfühlt.

Die Überlagerungs-API für Fenstersteuerelemente bewirkt Folgendes:

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

Eine Progressive Web App (PWA) kann definieren, wie sie auf mobilen Plattformen angezeigt werden soll, indem sie den Anzeigemember in der Web-App-Manifestdatei verwendet. Um jedoch eine immersive, native-ähnliche 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 direkt unter dem reservierten Titelleistenbereich beginnt:

Eine PWA-App unter Windows, die zeigt, dass der App-Inhalt unterhalb des reservierten Titelleistenbereichs angezeigt wird

Das Anzeigen von Inhalten, wo sich die Titelleiste normalerweise befindet, kann PWAs helfen, sich nativer zu fühlen. Viele Desktopanwendungen, z. B. Visual Studio Code, Microsoft Teams und Microsoft Edge tun dies bereits:

Visual Studio Code zeigt Inhalte im Titelleistenbereich an

Aktivieren der Windows-Steuerelementüberlagerung in Ihrer App

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

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

Siehe auch:

Verwenden Sie CSS-Umgebungsvariablen, um Überlagerungen fernzuhalten

Die env() CSS-Funktion kann verwendet werden, um auf Umgebungsvariablen zuzugreifen, die vom Benutzeragenten definiert werden.

Vier Umgebungsvariablen werden von der Überlagerungsfunktion für Fenstersteuerelemente hinzugefügt:

Variable Beschreibung
titlebar-area-x Abstand in , des Bereichs, pxder normalerweise von der Titelleiste von der linken Fensterseite eingenommen wird
titlebar-area-y Abstand in px, des Bereichs, der normalerweise von der Titelleiste von der oberen Seite des Fensters eingenommen wird
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 dort zu positionieren und anzupassen, wo normalerweise die Titelleiste angezeigt wird, wenn das Überlagerungsfeature 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%);
}

Mit wird position: fixed; 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 zum Definieren der Position Ihres App-Inhalts nützlich ist, wenn das Überlagerungsfeature für Fenstersteuerelemente fehlt oder deaktiviert ist.

Festlegen einer Region 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 den Benutzern nur sehr wenig Platz zum Verschieben des Anwendungsfensters zur Verfügung steht.

Sie können die app-region CSS-Eigenschaft verwenden, um Benutzern mehr Möglichkeiten zum Ziehen der App anzubieten. Wenn Ihre App beispielsweise über eine eigene Titelleiste verfügt, können Sie deren 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%);
  app-region: drag;
}

React to overlay changes

Ein Benutzer kann die Titelleiste umschalten oder die Fensterabmessungen ändern, während die App ausgeführt wird. Zu wissen, wann diese Dinge geschehen, kann für Ihre App wichtig sein. Möglicherweise muss Ihre App einige der Inhalte, die in der Titelleiste angezeigt werden, neu anordnen 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 erkennen, ob die Titelleiste sichtbar ist, verwenden Sie die visible Eigenschaft des navigator.windowControlsOverlay Objekts.

Das geometrychange Ereignis wird sehr häufig ausgelöst, wenn der Benutzer die Größe des Fensters ändert. Um zu vermeiden, dass Sie layoutändernden Code zu häufig ausführen und Leistungsprobleme in Ihrer App verursachen, verwenden Sie eine debounce Funktion, um die Anzahl der Behandlungen des Ereignisses einzuschränken. Siehe Der Unterschied zwischen Drosselung und Entprellung.

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 "Window Controls Overlay" verwendet.

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

  2. Klicken Sie in der Adressleiste auf die verfügbare App. Installieren Sie 1DIV (das ). 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, wobei der Dialog "App installiert" geöffnet ist:

    Die 1DIV-App in einem eigenen Fenster mit dem Dialog

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

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

    Symbol Tooltip
    Das Symbol Einstellungen und mehr
    Das Symbol Minimize
    Das Symbol Wiederherstellen
    Das Symbol Close

    Die App zeigt Inhalte jetzt bis zum oberen Rand des Fensterrahmens an, wo sich die Titelleiste vorher befand:

    Der obere Bereich der Karte kann zum Verschieben des Fensters verwendet werden

    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 Overlay-Features für Fenstersteuerelemente durch die App.

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

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

Anzeigen einer Vorschau der benutzerdefinierten Überlagerung ohne Installation von PWA

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

Bei der simulierten Überlagerung handelt es sich um 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) sind so eingestellt, dass sie der von Ihnen ausgewählten Plattform entsprechen.

Weitere Informationen finden Sie unter Simulieren der Überlagerungs-API für Fenstersteuerelemente ohne Installation Ihrer PWA.

Siehe auch

MDN:

Blog:

YouTube-Plattform:

Demo:

  • Last updated on