Anzeigen von Inhalten in der Titelleiste

Artikel
04/04/2023

Eine 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:

Eine PWA-App unter Windows, die anzeigt, dass der App-Inhalt unter dem reservierten Titelleistenbereich angezeigt wird

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:

Visual Studio Code zeigt Inhalt im Titelleistenbereich an

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.

Aktivieren der Fenstersteuerelementüberlagerung in Ihrer App

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

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

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 React zum Überlagern von Ä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 `px`des Bereichs, der normalerweise von der Titelleiste belegt wird, von der linken Seite des Fensters
`titlebar-area-y`	Abstand in `px`des 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.

Erstellen von Bereichen ihrer App zum Ziehen von Handlern 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 Fensterziehhandler 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;
}

React zu Ü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.

Wechseln Sie in Microsoft Edge zu 1DIV , und installieren Sie die App.
Klicken Sie in der App-Titelleiste auf Titelleiste ausblenden .

Die App zeigt nun Inhalte bis zum oberen Rand des Fensterrahmens an, wo sich früher die Titelleiste war. Der obere Bereich der App ist ein Ziehhandler, 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 "Überlagerung von Fenstersteuerelementen" durch die App.
Die app.js Quelldatei verwendet das navigator.windowControlsOverlay -Objekt.
Die Quelldatei app.css verwendet die titlebar-area-* CSS-Umgebungsvariablen.