env() CSS-Funktion

Syntax

/* Without a fallback value */
env(safe-area-inset-top);
env(titlebar-area-width);
env(viewport-segment-right 0 0);

/* With a fallback value */
env(safe-area-inset-right, 1em);
env(titlebar-area-y, 40px);
env(viewport-segment-width 0 0, 40%);

Parameter

Die env( <environment-variable>, <fallback> ) Funktion akzeptiert die folgenden Parameter:

<environment-variable>

Ein <custom-ident>, der den Namen der Umgebungsvariablen angibt, die eingefügt werden soll. Wenn der angegebene Name eine array-ähnliche Umgebungsvariable darstellt, folgt dem Namen ein <integer>-Wert, der die spezifische Instanz identifiziert, auf die sich der Name bezieht. Der case-sensitive Name der Umgebungsvariablen kann einer der folgenden sein:

safe-area-inset-top, safe-area-inset-right, safe-area-inset-bottom, safe-area-inset-left

Der sichere Abstand von der oberen, rechten, unteren oder linken Einfügekante des Ansichtsfensters, der angibt, wo Inhalte eingefügt werden können, ohne dass das Risiko besteht, dass sie durch die Form eines nicht-rechteckigen Displays abgeschnitten werden. Die vier Werte bilden ein Rechteck, innerhalb dessen alle Inhalte sichtbar sind. Die Werte sind 0, wenn das Ansichtsfenster ein Rechteck ist und keine Funktionen — wie Toolbars oder dynamische Tastaturen — Platz im Ansichtsfenster einnehmen; andernfalls ist es ein px-Wert, der größer als 0 ist.

safe-area-max-inset-top, safe-area-max-inset-right, safe-area-max-inset-bottom, safe-area-max-inset-left

Die statischen Maximalwerte ihrer dynamischen Gegenstücke der safe-area-inset-*-Variablen, wenn alle dynamischen Benutzeroberflächenfunktionen zurückgezogen sind. Während sich die safe-area-inset-*-Werte ändern, wenn der derzeit sichtbare Inhaltsbereich sich ändert, sind die safe-area-max-inset-*-Werte Konstanten.

titlebar-area-x, titlebar-area-y, titlebar-area-width, titlebar-area-height

Die Dimensionen eines sichtbaren titlebar-area-*-Bereichs. Diese Variablen stehen zur Verfügung, wenn das window-controls-overlay display_override Manifestfeld verwendet wird. Die Variablenwerte können verwendet werden, um sicherzustellen, dass Inhalte nicht Fenstersteuerungsschaltflächen (also Minimieren, Maximieren und Schließen) bei progressiven Web-Apps (PWA), die auf Desktop-Geräten installiert sind, überlappen.

keyboard-inset-top, keyboard-inset-right, keyboard-inset-bottom, keyboard-inset-left, keyboard-inset-width, keyboard-inset-height

Die Einfügungen von der Kante des Ansichtsfensters und die Abmessungen der virtuellen Bildschirmtastatur des Geräts. Definiert in der VirtualKeyboard API.

viewport-segment-width, viewport-segment-height, viewport-segment-top, viewport-segment-right, viewport-segment-bottom, viewport-segment-left

Die Abmessungen und Offset-Positionen bestimmter Ansichtsfenstersegmente. Das viewport-segment-*-Schlüsselwort wird von zwei leerzeichengetrennten <integer>-Werten gefolgt, die die horizontale und vertikale Position oder Indizes des Segments angeben. Die viewport-segment-Schlüsselwörter sind nur definiert, wenn das Ansichtsfenster aus zwei oder mehr Segmenten besteht, wie bei faltbaren oder klappbaren Geräten.

<fallback> Optional

Ein Fallback-Wert, der eingefügt wird, wenn die in dem ersten Argument referenzierte Umgebungsvariable nicht existiert. Alles, was nach dem ersten Komma kommt, wird als Fallback-Wert angesehen. Dies kann ein einzelner Wert, eine weitere env()-Funktion oder eine kommagetrennte Liste von Werten sein.

Beschreibung

Die env()-Funktion wird verwendet, um den Wert einer globalen, vom Benutzeragenten definierten Umgebungsvariablen in Ihr CSS einzufügen. Die env()-Funktion kann als Eigenschaftswert oder anstelle eines Teils eines Eigenschaftswerts oder Deskriptors verwendet werden (zum Beispiel in Media-Query-Regeln).

Die Funktion akzeptiert ein <environment-variable> als erstes Argument. Dies ist ein case-sensitives <custom-ident>, das dem Namen der Umgebungsvariablen entspricht, die ersetzt werden soll, kann jedoch auch zusätzliche leerzeichengetrennte Werte enthalten, falls erforderlich. Zum Beispiel würde env(viewport-segment-width 0 0) die Breite des oberen oder linken Segments im Fall eines Geräts mit mehreren Ansichtsfenster-Segmenten zurückgeben.

Das zweite Argument, falls bereitgestellt, ist der Fallback-Wert, der verwendet wird, wenn die im ersten Argument referenzierte Umgebungsvariable nicht unterstützt wird oder nicht existiert. Der Fallback kann eine andere Umgebungsvariable sein, sogar mit ihrem eigenen Fallback.

Die Syntax des Fallbacks ähnelt der Fallback-Syntax der var()-Funktion, die zum Einfügen von CSS-Benutzereigenschaften verwendet wird, insofern sie mehrere Kommata erlaubt. Alles zwischen dem ersten Komma und dem Ende der Funktion wird als Fallback-Wert betrachtet. Wenn jedoch die env()-Funktion innerhalb eines Eigenschaftswertes oder Deskriptors verwendet wird, der keine Kommata enthält, ist ein Fallback-Wert, der Kommata enthält, nicht gültig.

Eine Eigenschaft oder ein Deskriptor, der eine syntaktisch gültige env()-Funktion enthält, wird zur Zeit der Analyse als gültig angesehen, wenn der Browser zuerst den heruntergeladenen CSS-Text liest und interpretiert. Es wird nur zur Laufzeit der Berechnung auf Syntax überprüft, nachdem jede env()-Funktion durch ihren vom Browser bereitgestellten Wert (oder den Fallback-Wert, wenn die als erster Parameter übergebene Umgebungsvariable kein erkannter Name einer Umgebungsvariablen ist) ersetzt wurde. Wenn der Wert ungültig ist und kein Fallback bereitgestellt wird, ist die Eigenschaft oder der Deskriptor, der die env()-Funktion enthält, zur Laufzeit ungültig.

Wenn eine env()-Substitution ungültig ist und ein ungültiger Fallback eingeschlossen ist oder der Fallback weggelassen wird, wird die Deklaration nicht ignoriert. Stattdessen wird der Initialwert oder vererbte Wert der Eigenschaft verwendet. Die Eigenschaft wird auf einen neuen Wert gesetzt, aber es könnte nicht der erwartete sein.

Anwendungsfälle

Ursprünglich von iOS-Browsern bereitgestellt, um Entwicklern zu ermöglichen, ihre Inhalte in einem sicheren Bereich des Ansichtsfensters zu platzieren, ohne dass sie durch Geräteeinschnitte oder abgerundete Ecken verdeckt werden, können die safe-area-inset-*-Werte verwendet werden, um sicherzustellen, dass Inhalte für die Betrachter sichtbar sind. Diese Funktion wurde später über den ursprünglichen Zweck hinaus erweitert, um Anwendungsfälle wie das Verhindern, dass Gerätebenachrichtigungen Teile der App-Benutzeroberfläche verdecken zu ermöglichen.

Ein weiterer Anwendungsfall für env()-Variablen ist für Progressive Web Apps (PWAs) auf dem Desktop, die das Window Controls Overlay Feature nutzen, um die gesamte Fensterfläche der Anwendung zu nutzen. Mithilfe der titlebar-area-*-Werte können Entwickler Elemente dort positionieren, wo sich normalerweise die Titelleiste befunden hätte, und sicherstellen, dass Inhalte nicht durch Fenstersteuerungsschaltflächen verdeckt werden, die sich in PWAs befinden, die auf Desktop-Geräten installiert sind.

Die viewport-segment-*-Variablenbezeichnungen können verwendet werden, um Ihre Container nahtlos in die verfügbaren Segmente eines Multi-Viewport-Segment-Geräts, wie ein klappbares oder faltbares Gerät, einzufügen. Die auf die viewport-segment-*-Bezeichnung folgenden Ganzzahlen geben an, welches Segment der mehreren Segmente durch die Umgebungsvariable referenziert wird.

Namen gefolgt von Ganzzahlen

Wenn die Umgebungsvariable array-ähnlich ist, was bedeutet, der Name kann mehr als einen Wert referenzieren, wie es bei Geräten mit mehreren Ansichtsfenster-Segmenten der Fall ist, beinhaltet der <environment-variable>-Parameter sowohl den Namen der Variablen als auch die Indizes der spezifischen Instanz der Variablen, auf die die Funktion verweist. Zum Beispiel, im Fall der viewport-segment-*-Variablen werden die Variablennamen zusammen mit zwei Ganzzahlen, die die Indizes des Segments angeben, an die env()-Funktion übergeben, um den Wert für diese zu erhalten. Diese Werte sind beide Ganzzahlen von 0 oder größer. Die erste Ganzzahl repräsentiert den horizontalen Index des Segments, wobei 0 das linkeste Segment ist, und der zweite Wert repräsentiert den vertikalen Index des Segments, wobei 0 das unterste Segment ist:

• In einem horizontal nebeneinander angeordneten Layout wird das linke Segment durch 0 0 repräsentiert, und das rechte Segment wird durch 1 0 repräsentiert.
• In einem vertikalen, von oben nach unten angeordneten Layout wird das obere Segment durch 0 0 repräsentiert, und das untere Segment wird durch 0 1 repräsentiert.
• Bei Geräten mit mehr als zwei Segmenten könnten die Zahlen größer sein. Zum Beispiel könnte ein Gerät mit drei horizontalen Segmenten das mittlere Segment durch 1 0 repräsentieren und das rechte Segment durch 2 0.

Zum Beispiel gibt das folgende die Breite des rechten der beiden Segmente eines faltbaren Geräts zurück, bei dem die Segmente horizontal ausgerichtet sind:

env(viewport-segment-width 1 0)

Siehe das Viewport-Segment-API-Demo für eine voll funktionsfähige Demo (Quellcode). Schauen Sie sich auch Verwendung der Viewport-Segments-API für eine vollständige Demo-Erklärung an.

Formale Syntax

<env()> = 
  env( <custom-ident> <integer [0,∞]>* , <declaration-value>? )  

<integer> = 
  <number-token>  

Beispiele

Verwendung von env() um sicherzustellen, dass Schaltflächen nicht durch Gerät UI verdeckt werden

Im folgenden Beispiel wird env() verwendet, um sicherzustellen, dass feste Anwendungs-Toolbar-Schaltflächen nicht durch Gerätemitteilungen, die unten auf dem Bildschirm angezeigt werden, verdeckt werden. Auf dem Desktop ist safe-area-inset-bottom 0. Bei Geräten, die Benachrichtigungen unten auf dem Bildschirm anzeigen, wie iOS, enthält es jedoch einen Wert, der Platz für die Anzeige der Benachrichtigung lässt. Dies kann dann im Wert von padding-bottom verwendet werden, um eine Lücke zu schaffen, die auf dem Gerät natürlich erscheint.

HTML

Wir haben einen <main>-Abschnitt, der eine Fake-Anwendung enthält und einen <footer> mit zwei <button>-Elementen:

<main>Main content of app here</main>
<footer>
  <button>Go here</button>
  <button>Or here</button>
</footer>

CSS

Mit dem CSS-Flexible-Box-Layout erstellen wir einen Footer, der nur so hoch ist, wie er sein muss, während der Main-Bereich, der die Anwendung enthält, den Rest des Ansichtsfensters ausfüllt:

body {
  display: flex;
  flex-direction: column;
  min-height: 100vh;
  font: 1em system-ui;
}

main {
  flex: 1;
  background-color: #eeeeee;
  padding: 1em;
}

footer {
  flex: none;
  display: flex;
  gap: 1em;
  justify-content: space-evenly;
  background: black;
}

button {
  padding: 1em;
  background: white;
  color: black;
  margin: 0;
  width: 100%;
  border: none;
  font: 1em system-ui;
}

Wir setzen position: sticky, um den Footer am unteren Rand des Ansichtsfensters zu fixieren. Wir verwenden dann die padding-Kurzschreibweise, um dem Footer ein Padding hinzuzufügen. Wir fügen dem anfänglichen 1em-Puffer unten den Wert der safe-area-inset-bottom-Umgebung hinzu. Ein größerer schwarzer Bereich wird auf Geräten angezeigt, die einen positiven Wert für diese Variable haben, was sicherstellt, dass die Schaltflächen im Footer niemals verdeckt werden.

footer {
  position: sticky;
  bottom: 0;

  padding: 1em 1em calc(1em + env(safe-area-inset-bottom));
}

Ergebnisse

Verwendung eines Fallback-Werts

Dieses Beispiel nutzt den optionalen zweiten Parameter von env(), der einen Fallback-Wert bereitstellt, falls die Umgebungsvariable nicht verfügbar ist.

HTML

Wir fügen einen Absatz Text hinzu:

<p>
  If the <code>env()</code> function is supported in your browser, this
  paragraph's text will have 50px of padding between it and the left border —
  but not the top, right and bottom. This is because the accompanying CSS is the
  equivalent of <code>padding: 0 0 0 50px</code>, because, unlike other CSS
  properties, user agent property names are case-sensitive.
</p>

CSS

Wir setzen eine width von 300px und eine border. Wir fügen dann padding hinzu, indem wir die env()-Funktion mit einem Fallback für die Größe des Paddings auf jeder Seite verwenden. Wir setzen absichtlich einen ungültigen Wert für das linke Padding (denken Sie daran, dass Umgebungsvariablennamen case-sensitive sind), um die Verwendung des Fallback-Werts zu demonstrieren.

p {
  width: 300px;
  border: 2px solid red;
  padding: env(safe-area-inset-top, 50px) env(safe-area-inset-right, 50px)
    env(safe-area-inset-bottom, 50px) env(SAFE-AREA-INSET-LEFT, 50px);
}

Ergebnisse

Verwendung von env() um sicherzustellen, dass Inhalte nicht durch Fenstersteuerungsschaltflächen in Desktop-PWAs verdeckt werden

Im folgenden Beispiel stellt env() sicher, dass Inhalte, die in einer Desktop-Progressive-Web-App, die die Window Controls Overlay API verwendet, angezeigt werden, nicht durch die Fenstersteuerungsschaltflächen des Betriebssystems verdeckt werden. Die titlebar-area-*-Werte definieren ein Rechteck, wo normalerweise die Titelleiste angezeigt worden wäre. Bei Geräten, die die Window-Controls-Overlay-Funktion nicht unterstützen, wie mobile Geräte, werden die Fallback-Werte verwendet.

So sieht eine PWA, die auf einem Desktop-Gerät installiert ist, normalerweise aus:

Mit der Window-Controls-Overlay-Funktion bedecken die Webinhalte die gesamte Fensterfläche der App, wobei die Fenstersteuerungen und PWA-Schaltflächen als Überlagerungen angezeigt werden:

<header>Title of the app here</header>
<main>Main content of app here</main>

header {
  position: fixed;
  left: env(titlebar-area-x);
  top: env(titlebar-area-y);
  width: env(titlebar-area-width);
  height: env(titlebar-area-height);
}

main {
  margin-top: env(titlebar-area-height);
}

Ansichtsfenster-Segmente

Das Viewport-Segment-API-Demo und der Verwendung der Viewport-Segments-API Leitfaden bietet eine Demonstration und Erklärung der Verwendung der env()-Funktion mit den viewport-segments-*-Umgebungsvariablen.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Verwendung von Umgebungsvariablen
• CSS-Umgebungsvariablen Modul
• var()
• CSS-Benutzereigenschaften für kaskadierende Variablen Modul
• Benutzereigenschaften (--*): CSS-Variablen
• Verwendung von CSS-Benutzereigenschaften (Variablen)
• Viewport-Segments API
• Passen Sie das Fenstersteuerungs-Overlay der Titelleiste Ihrer PWA an
• Inhalte in der Titelleiste anzeigen
• Ausbrechen aus dem Rahmen