Overlay der Fenstersteuerelemente in der Titelleiste der PWA anpassen

Verwenden Sie den Titelleistenbereich neben den Fenstersteuerelementen, damit Ihre PWA eher wie eine App wirkt.

Amanda Baker

Thomas Steiner

Sie erinnern sich vielleicht an meinen Artikel Eine PWA als App gestalten? Dann erinnern Sie sich vielleicht noch. wie ich bereits erwähnt habe, die Titelleiste Ihrer App anzupassen, eine App-ähnliche Strategie zu entwickeln. Hier ist ein Beispiel, wie dies mit der macOS Podcasts App.

</ph> <ph type="x-smartling-placeholder">

Es mag verlockend sein, zu widersprechen, wenn Sie sagen, dass Podcasts eine plattformspezifische macOS-App ist, die nicht in einem Browser ausgeführt werden und daher das tun können, was er möchte, ohne Regeln. Richtig, aber die gute Nachricht ist, dass die Funktion Fenstersteuerelemente-Overlay, die das Thema In diesem Artikel erfahren Sie bald, wie Sie ähnliche Benutzeroberflächen für Ihre PWA erstellen können.

Overlay-Komponenten für Fenstersteuerelemente

Das Overlay für Fenstersteuerelemente besteht aus vier Unterfunktionen:

1. Der Wert "window-controls-overlay" für das Feld "display_override" in Web-App-Manifests.
2. Die CSS-Umgebungsvariablen titlebar-area-x, titlebar-area-y, titlebar-area-width und titlebar-area-height.
3. Die Standardisierung der zuvor proprietären CSS-Eigenschaft -webkit-app-region als app-region, um ziehbare Bereiche im Webinhalt zu definieren.
4. Ein Mechanismus zur Abfrage und Umgehung des Fenstersteuerungsbereichs über die windowControlsOverlay Mitglied von „window.navigator“

Was ist das Overlay der Fenstersteuerelemente

Der Bereich der Titelleiste bezieht sich auf den Bereich links oder rechts neben den Fenstersteuerelementen (d. h. der Bereich zum Minimieren, Maximieren, Schließen usw. enthält und enthält häufig den Titel der Anwendung. Fenster Mit Steuerelementen-Overlays können progressive Web-Apps (PWAs) durch Austausch von zwischen verschiedenen die bestehende Titelleiste in voller Breite für ein kleines Overlay mit den Fenstersteuerelementen. Dadurch können Sie Entwickelnden benutzerdefinierte Inhalte dort platzieren, wo sie zuvor browsergesteuerter Titelleistenbereich war.

Aktueller Status

Overlay für Fenstersteuerelemente verwenden

window-controls-overlay zum Web-App-Manifest hinzufügen

Eine progressive Web-App kann das Overlay der Fenstersteuerelemente aktivieren, indem "window-controls-overlay" als primäres "display_override"-Mitglied im Manifest der Web-App:

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

Das Overlay der Fenstersteuerelemente ist nur sichtbar, wenn alle der folgenden Bedingungen erfüllt sind:

1. Die App wird nicht im Browser, sondern in einem separaten PWA-Fenster geöffnet.
2. Das Manifest enthält "display_override": ["window-controls-overlay"]. (Andere Werte sind anschließend zulässig.)
3. Die PWA wird in einem Computerbetriebssystem ausgeführt.
4. Der aktuelle Ursprung stimmt mit dem Ursprung überein, für den die PWA installiert wurde.

Das Ergebnis ist ein leerer Titelleistenbereich mit den normalen Fenstersteuerelementen auf der linken Seite oder der je nach Betriebssystem.

</ph> <ph type="x-smartling-placeholder">

Inhalte in die Titelleiste verschieben

Jetzt, da in der Titelleiste Platz ist, können Sie etwas dorthin verschieben. In diesem Artikel eine Wikimedia Featured Content PWA erstellt. Eine nützliche Funktion für diese App ist die Suche nach Wörtern in die Artikeltitel. Der HTML-Code für die Suchfunktion sieht wie folgt aus:

<div class="search">
  <img src="logo.svg" alt="Wikimedia logo." width="32" height="32" />
  <label>
    <input type="search" />
    Search for words in articles
  </label>
</div>

Um dieses Element (div) nach oben in die Titelleiste zu verschieben, wird CSS-Code benötigt:

.search {
  /* Make sure the `div` stays there, even when scrolling. */
  position: fixed;
  /**
   * Gradient, because why not. Endless opportunities.
   * The gradient ends in `#36c`, which happens to be the app's
   * `<meta name="theme-color" content="#36c">`.
   */
  background-image: linear-gradient(90deg, #36c, #131313, 33%, #36c);
  /* Use the environment variable for the left anchoring with a fallback. */
  left: env(titlebar-area-x, 0);
  /* Use the environment variable for the top anchoring with a fallback. */
  top: env(titlebar-area-y, 0);
  /* Use the environment variable for setting the width with a fallback. */
  width: env(titlebar-area-width, 100%);
  /* Use the environment variable for setting the height with a fallback. */
  height: env(titlebar-area-height, 33px);
}

Die Auswirkungen dieses Codes können Sie im folgenden Screenshot sehen. Die Titelleiste ist vollständig responsiv. Wann? Sie die Größe des PWA-Fensters ändern, reagiert die Titelleiste so, als wäre sie aus normalem HTML-Inhalt bestehen. was tatsächlich so ist.

</ph> <ph type="x-smartling-placeholder">

Festlegen, welche Teile der Titelleiste ziehbar sind

Der Screenshot oben zeigt an, dass Sie fertig sind, aber Sie sind noch nicht ganz fertig. Das PWA-Fenster ist nicht mehr ziehbar (bis auf einen sehr kleinen Bereich), da die Schaltflächen für die Fenstersteuerelemente nicht Der Rest der Titelleiste besteht aus dem Such-Widget. Beheben Sie das Problem mit die CSS-Eigenschaft app-region mit dem Wert drag. Im konkreten Fall ist es in Ordnung, alles außer dem input-Element ziehbar.

/* The entire search `div` is draggable… */
.search {
  -webkit-app-region: drag;
  app-region: drag;
}

/* …except for the `input`. */
input {
  -webkit-app-region: no-drag;
  app-region: no-drag;
}

Anschließend kann der Nutzer das App-Fenster wie gewohnt ziehen, indem er die div, die img, oder die label. Nur das input-Element ist interaktiv, sodass die Suchanfrage eingegeben werden kann.

Funktionserkennung

Die Unterstützung des Overlays für Fenstersteuerelemente kann durch Testen auf das Vorhandensein von windowControlsOverlay:

if ('windowControlsOverlay' in navigator) {
  // Window Controls Overlay is supported.
}

Bereich für Fenstersteuerelemente mit windowControlsOverlay abfragen

Der Code weist bisher ein Problem auf: Auf einigen Plattformen befinden sich die Fenstersteuerelemente auf der rechten Seite, auf der linken Seite. Die drei Punkte Chrome-Menü ändert sich basierend auf der Plattform. Das bedeutet, dass das Hintergrundbild mit dem linearen Farbverlauf dynamisch für #131313→maroon oder maroon→#131313→maroon angepasst werden, sodass fügt sich der maroon-Hintergrundfarbe der Titelleiste ein, die durch <meta name="theme-color" content="maroon"> Dies kann durch Abfragen des getTitlebarAreaRect() API für das Attribut navigator.windowControlsOverlay.

if ('windowControlsOverlay' in navigator) {
  const { x } = navigator.windowControlsOverlay.getTitlebarAreaRect();
  // Window controls are on the right (like on Windows).
  // Chrome menu is left of the window controls.
  // [ windowControlsOverlay___________________ […] [_] [■] [X] ]
  if (x === 0) {
    div.classList.add('search-controls-right');
  }
  // Window controls are on the left (like on macOS).
  // Chrome menu is right of the window controls overlay.
  // [ [X] [_] [■] ___________________windowControlsOverlay [⋮] ]
  else {
    div.classList.add('search-controls-left');
  }
} else {
  // When running in a non-supporting browser tab.
  div.classList.add('search-controls-right');
}

Das Hintergrundbild muss nicht wie zuvor direkt in die CSS-Regeln der .search-Klasse aufgenommen werden. verwendet nun zwei Klassen, die im obigen Code dynamisch festgelegt werden.

/* For macOS: */
.search-controls-left {
  background-image: linear-gradient(90deg, #36c, 45%, #131313, 90%, #36c);
}

/* For Windows: */
.search-controls-right {
  background-image: linear-gradient(90deg, #36c, #131313, 33%, #36c);
}

Es wird ermittelt, ob das Overlay der Fenstersteuerelemente sichtbar ist

Das Overlay der Fenstersteuerelemente ist unter keinen Umständen im Bereich der Titelleiste sichtbar. Während es in Browsern, die die Overlay-Funktion der Fenstersteuerelemente nicht unterstützen, sind ebenfalls nicht vorhanden, wenn die betreffende PWA auf einem Tab ausgeführt wird. Um diese Situation zu erkennen, können Sie das Attribut visible von windowControlsOverlay abfragen:

if (navigator.windowControlsOverlay.visible) {
  // The window controls overlay is visible in the title bar area.
}

Alternativ können Sie die Medienabfrage display-mode auch in JavaScript und/oder CSS verwenden:

// Create the query list.
const mediaQueryList = window.matchMedia('(display-mode: window-controls-overlay)');

// Define a callback function for the event listener.
function handleDisplayModeChange(mql) {
  // React on display mode changes.
}

// Run the display mode change handler once.
handleDisplayChange(mediaQueryList);

// Add the callback function as a listener to the query list.
mediaQueryList.addEventListener('change', handleDisplayModeChange);

@media (display-mode: window-controls-overlay) { 
  /* React on display mode changes. */ 
}

Benachrichtigung über Geometrieänderungen

Das Abfragen des Overlay-Bereichs der Fenstersteuerelemente mit getTitlebarAreaRect() kann für eine einmalige Abfrage ausreichen wie das richtige Hintergrundbild eingestellt wird, je nachdem, wo sich die Fenstersteuerelemente befinden, in anderen Fällen ist eine genauere Kontrolle erforderlich. Ein möglicher Anwendungsfall könnte sein, Passen Sie das Overlay der Fenstersteuerelemente an den verfügbaren Platz an und fügen Sie einen Witz direkt im Fenster hinzu. ein Kontroll-Overlay, wenn genügend Platz vorhanden ist.

</ph> <ph type="x-smartling-placeholder">

Sie können sich über Geometrieänderungen benachrichtigen lassen, indem Sie navigator.windowControlsOverlay.ongeometrychange oder indem Sie einen Event-Listener für die Ereignis vom Typ geometrychange. Dieses Ereignis wird nur ausgelöst, wenn das Overlay für die Fenstersteuerelemente sichtbar ist, das ist, wenn navigator.windowControlsOverlay.visible gleich true ist.

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.ongeometrychange = debounce((e) => {
    span.hidden = e.titlebarAreaRect.width < 800;
  }, 250);
}

Anstatt ongeometrychange eine Funktion zuzuweisen, können Sie auch einen Ereignis-Listener zu windowControlsOverlay, wie unten dargestellt. Informationen zum Unterschied zwischen den beiden MDN

navigator.windowControlsOverlay.addEventListener(
  'geometrychange',
  debounce((e) => {
    span.hidden = e.titlebarAreaRect.width < 800;
  }, 250),
);

Kompatibilität bei der Ausführung in einem Tab und mit nicht unterstützten Browsern

Es gibt zwei mögliche Fälle:

• Eine App wird in einem Browser ausgeführt, der das Overlay der Fenstersteuerelemente unterstützt, aber bei denen die App in einem Browsertab verwendet wird.
• Der Fall, wenn eine App in einem Browser ausgeführt wird, der das Overlay der Fenstersteuerelemente nicht unterstützt.

In beiden Fällen ist standardmäßig der HTML-Code, der für die Fenstersteuerelemente erstellt wurde, das Overlay wird inline wie normaler HTML-Inhalt und die env()-Variablen angezeigt. Fallback-Werte bei der Positionierung ins Spiel. Bei Browsern, die diese Funktion unterstützen, können Sie auch festlegen, dass der HTML-Code, der für das Overlay der Fenstersteuerelemente bestimmt ist, indem Sie die Eigenschaft visible des Overlays aktivieren und falls meldet false und blendet dann den HTML-Inhalt aus.

</ph> <ph type="x-smartling-placeholder">

Zur Erinnerung: In nicht unterstützten Browsern wird die "display_override"-Web-App-Manifest-Property oder erkennt die "window-controls-overlay" und verwenden somit den nächstmöglichen Wert gemäß der Fallback-Kette. Beispiel: "standalone".

</ph> <ph type="x-smartling-placeholder">

Hinweise zur Benutzeroberfläche

Es mag verlockend sein, aber wir raten davon ab, ein klassisches Dropdown-Menü im Overlay-Bereich der Fenstersteuerelemente zu erstellen. Dies würde gegen die Designrichtlinien für macOS, eine Plattform, auf der Nutzende Menüleisten erwarten (sowohl vom System bereitgestellte als auch benutzerdefinierte Anzeigen) oben auf dem Bildschirm.

Wenn Ihre App eine Vollbildansicht bietet, überlegen Sie sorgfältig, ob sie sinnvoll ist. um das Overlay für Fenstersteuerelemente in die Vollbildansicht aufzunehmen. Möglicherweise Ihr Layout neu anordnen möchten, onfullscreenchange ausgelöst wird.

Demo

Ich habe eine Demo erstellt, mit der Sie in verschiedene unterstützende und nicht unterstützende Browser in installiertem und nicht installiertem Zustand sind. Für die eigentlichen Fenstersteuerelemente einblenden, müssen Sie die App installieren. Unten siehst du zwei Screenshots, die den Ablauf des Ablaufs verdeutlichen. Die Quellcode für die App ist in Glitch verfügbar.

</ph> <ph type="x-smartling-placeholder">

Die Suchfunktion im Overlay der Fenstersteuerelemente ist voll funktionsfähig:

</ph> <ph type="x-smartling-placeholder">

Sicherheitsaspekte

Das Chromium-Team hat die Window Controls Overlay API nach den Grundprinzipien entwickelt und implementiert. wie unter Zugriff auf leistungsstarke Webplattform-Funktionen steuern beschrieben, einschließlich Transparenz und Ergonomie.

Spoofing

Wenn Sie Websites die teilweise Kontrolle über die Titelleiste geben, haben Entwickler die Möglichkeit, Inhalte in welcher Form zu fälschen. war zuvor eine vertrauenswürdige, vom Browser gesteuerte Region. Derzeit ist es in Chromium-Browsern möglich, enthält eine Titelleiste, in der beim ersten Start links der Titel der Webseite angezeigt wird. den Ursprung der Seite auf der rechten Seite (gefolgt von der Schaltfläche „Einstellungen und mehr“ und dem Fenster Steuerelementen). Nach einigen Sekunden verschwindet der Ausgangstext. Wenn im Browser die Leserichtung von rechts nach links eingestellt ist, RTL-Sprache, wird dieses Layout so umgedreht, dass sich der Ausgangstext auf der linken Seite befindet. Dadurch wird die Overlay für Fenstersteuerelemente, um den Ursprung zu spoofen, wenn der Abstand zwischen Ursprung und rechten Rand des Overlays. Beispiel: Der Ursprung „evil.ltd“ könnte eine vertrauenswürdige Website „google.com“, sodass Nutzer glauben, dass die Quelle vertrauenswürdig ist. Unser Plan ist es, diese Ursprungstext, damit Nutzer den Ursprung der App kennen und sicherstellen können, dass er mit ihrem Erwartungen erfüllt. Bei Browsern mit RTL-Konfiguration muss rechts vom Ursprung ausreichend Abstand vorhanden sein. um zu verhindern, dass eine schädliche Website den unsicheren Ursprung mit einer vertrauenswürdigen Quelle anhängt.

Fingerprinting

Durch das Aktivieren der Fenstersteuerelemente können Overlay- und ziehbare Bereiche nicht dargestellt werden. neben der Funktionserkennung weitreichende Bedenken im Hinblick auf den Datenschutz. Aufgrund der unterschiedliche Größen und Positionen der Steuerungsschaltflächen für das Fenster Systeme, die navigator.windowControlsOverlay.getTitlebarAreaRect() gibt die Methode DOMRect zurück. deren Position und Abmessungen Informationen über das Betriebssystem enthalten, den der Browser ausführt. Derzeit können Entwickler das Betriebssystem bereits aus dem User-Agent-String entfernt. Aufgrund von Fingerprinting-Effekten Diskussion über das Einfrieren des UA-Strings und die Vereinheitlichung von Betriebssystemversionen. Es gibt eine fortlaufende Bemühungen in der Browser-Community, zu verstehen, Die Größe des Overlays für Fenstersteuerelemente ändert sich plattformübergreifend, da die aktuelle dass diese bei allen Betriebssystemversionen relativ stabil sind und daher ist nützlich, um Nebenversionen des Betriebssystems zu beobachten. Obwohl dies ein potenzielles Fingerprinting-Problem auftritt, betrifft nur installierte PWAs, die die benutzerdefinierte Titelleistenfunktion und gilt nicht für die allgemeine Browsernutzung. Darüber hinaus enthält der navigator.windowControlsOverlay API ist nicht verfügbar für iFrames, die in eine PWA eingebettet sind.

Navigation

Wenn Sie innerhalb einer PWA zu einem anderen Ursprung navigieren, greift sie auf die normale eigenständige Version zurück. Titelleiste auch dann, wenn sie die oben genannten Kriterien erfüllt und mit dem Overlay für Fenstersteuerelemente gestartet wird. Damit wird die schwarze Leiste angepasst, die bei der Navigation zu einem anderen Startpunkt angezeigt wird. Nachher wieder zum ursprünglichen Ursprungsort zurückgekehrt ist, wird wieder das Overlay der Fenstersteuerelemente verwendet.

</ph> <ph type="x-smartling-placeholder">

Feedback

Das Chromium-Team möchte mehr über deine Erfahrungen mit der Window Controls Overlay API erfahren.

Informationen zum API-Design

Funktioniert die API nicht wie erwartet? Oder fehlen Methoden, oder Eigenschaften, die Sie für die Umsetzung Ihrer Idee benötigen? Fragen oder Kommentare zur Sicherheit haben Modell? Reichen Sie ein Spezifikationsproblem im entsprechenden GitHub-Repository ein oder fügen Sie Ihre Gedanken zu einem Problem zu beheben.

Problem mit der Implementierung melden

Hast du einen Fehler bei der Implementierung von Chromium gefunden? Oder weicht die Implementierung von der Spezifikation ab? Melde einen Fehler unter new.crbug.com. Geben Sie so viele Details wie möglich an, einfache Anweisungen zur Reproduktion und gib UI>Browser>WebAppInstalls in das Feld Komponenten ein. . Glitch eignet sich hervorragend, um schnelle und einfache Reproduktionen zu teilen.

Unterstützung für die API anzeigen

Möchten Sie die Window Controls Overlay API verwenden? Dein öffentlicher Support hilft dem Chromium-Team um Funktionen zu priorisieren und anderen Browseranbietern zu zeigen, wie wichtig es für ihre Unterstützung ist.

Sende einen Tweet an @ChromiumDev mit dem #WindowControlsOverlay und teilen Sie uns mit, wo und wie Sie ihn nutzen.

Nützliche Links

• Erklärung
• Entwurf der Spezifikationen
• Chromium-Fehler
• Eintrag zum Chrome-Plattformstatus
• TAG-Überprüfung
• Dokumente für Microsoft Edge

Danksagungen

Das Fenstersteuerungs-Overlay wurde implementiert und spezifiziert durch Amanda Baker vom Microsoft Edge-Team Dieser Artikel wurde von Joe Medley geprüft und Kenneth Rohde Christiansen. Hero-Image von Sigmund auf Unsplash