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

<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
  <path fill="env(--color, black)" d="..." />
</svg>

Parameter

Die Funktion env( <environment-variable> | <dashed-ident>, <fallback> | <declaration-value> ) akzeptiert die folgenden Parameter:

<environment-variable>

Ein <custom-ident>, das den Namen der einzufügenden Umgebungsvariablen angibt. Wenn der angegebene Name eine arrayartige Umgebungsvariable bezeichnet, folgen auf den Namen <integer>-Werte, die die betreffende Instanz identifizieren. Der Name der Umgebungsvariablen unterscheidet zwischen Groß- und Kleinschreibung und kann einer der folgenden sein:

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

Der sichere Abstand vom oberen, rechten, unteren oder linken Rand des Viewports. Er legt fest, wo Inhalte platziert werden können, ohne 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 der Viewport rechteckig ist und keine Elemente – etwa Symbolleisten oder dynamische Tastaturen – Platz im Viewport belegen. Andernfalls handelt es sich um einen px-Wert größer als 0.

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

Die statischen Maximalwerte der entsprechenden dynamischen safe-area-inset-*-Variablen, wenn alle dynamischen Elemente der Benutzeroberfläche ausgeblendet sind. Während sich die safe-area-inset-*-Werte mit dem aktuell sichtbaren Inhaltsbereich ändern, bleiben die safe-area-max-inset-*-Werte konstant.

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

Die Abmessungen eines sichtbaren titlebar-area-*-Bereichs. Diese Variablen sind verfügbar, wenn im Manifestfeld display_override window-controls-overlay verwendet wird. Mit ihren Werten lässt sich verhindern, dass Inhalte in auf Desktopgeräten installierten Progressive Web Apps (PWAs) die Schaltflächen zur Fenstersteuerung – zum Minimieren, Maximieren und Schließen – überlappen.

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

Die Abstände zu den Rändern des Viewports und die Abmessungen der virtuellen Bildschirmtastatur des Geräts. Sie sind in der VirtualKeyboard API definiert.

preferred-text-scale

Der vom Benutzer bevorzugte Skalierungsfaktor für Schrift, eine Zahl, die in den Einstellungen des Browsers oder Betriebssystems festgelegt wird. Damit können Inhalte proportional zu den dort festgelegten Schriftgrößen skaliert werden.

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

Die Abmessungen und Versatzpositionen bestimmter Viewport-Segmente. Auf das Schlüsselwort viewport-segment-* folgen zwei durch Leerzeichen getrennte <integer>-Werte, die die horizontale und vertikale Position beziehungsweise die Indizes des Segments angeben. Die viewport-segment-*-Schlüsselwörter sind nur definiert, wenn der Viewport aus mindestens zwei Segmenten besteht, etwa bei faltbaren Geräten oder Geräten mit Scharnier.

<dashed-ident>

Ein <dashed-ident> ist eine benutzerdefinierte Variable, die in der CSS-Funktion param() als Bezeichner verwendet werden kann, um den Wert zu aktualisieren.

<fallback> Optional

Ein Ersatzwert, der eingefügt wird, wenn die im ersten Argument angegebene Umgebungsvariable nicht existiert. Alles nach dem ersten Komma gilt als Ersatzwert. Dies kann ein einzelner Wert, eine weitere env()-Funktion oder eine durch Kommas getrennte Liste von Werten sein.

<declaration_value> Optional

Ein <declaration_value> ist der Standardwert des SVG-Attributs, das dynamisch gesetzt wird. Wird <declaration-value> weggelassen, steht es für einen leeren Wert.

Beschreibung

Die Funktion env() fügt den Wert einer global verfügbaren, vom User-Agent definierten Umgebungsvariablen in Ihr CSS ein. env() kann als Eigenschaftswert oder anstelle eines beliebigen Teils eines Eigenschaftswerts oder Deskriptors verwendet werden, beispielsweise in Media-Query-Regeln.

Die Funktion erwartet als erstes Argument eine <environment-variable>. Dabei handelt es sich um ein <custom-ident>, das zwischen Groß- und Kleinschreibung unterscheidet und dem Namen der zu ersetzenden Umgebungsvariablen entspricht. Falls erforderlich, kann das Argument zusätzlich durch Leerzeichen getrennte Werte enthalten. Beispielsweise würde env(viewport-segment-width 0 0) auf einem Gerät mit mehreren Viewport-Segmenten die Breite des oberen oder linken Segments zurückgeben.

Das zweite Argument ist optional und gibt den Ersatzwert an, der verwendet wird, wenn die im ersten Argument angegebene Umgebungsvariable nicht unterstützt wird oder nicht existiert. Der Ersatzwert kann selbst eine andere Umgebungsvariable sein, auch mit eigenem Ersatzwert.

Die Syntax des Ersatzwerts ähnelt derjenigen der Funktion var() zum Einfügen benutzerdefinierter CSS-Eigenschaften: Sie erlaubt mehrere Kommas. Alles zwischen dem ersten Komma und dem Ende der Funktion gilt als Ersatzwert. Wenn env() jedoch innerhalb eines Eigenschaftswerts oder Deskriptors verwendet wird, der keine Kommas zulässt, ist ein Ersatzwert mit Kommas ungültig.

Eine Eigenschaft oder ein Deskriptor mit einer syntaktisch gültigen env()-Funktion gilt beim Parsen zunächst als gültig, wenn der Browser den heruntergeladenen CSS-Text erstmals liest und interpretiert. Die Syntax wird erst bei der Berechnung geprüft, nachdem jede env()-Funktion durch den vom Browser bereitgestellten Wert ersetzt wurde – oder durch den Ersatzwert, falls das erste Argument kein erkannter Name einer Umgebungsvariablen ist. Ist der Wert ungültig und wurde kein Ersatzwert angegeben, ist die Eigenschaft oder der Deskriptor mit der env()-Funktion zum Zeitpunkt der Berechnung des Werts ungültig.

Ist eine env()-Ersetzung ungültig und ein angegebener Ersatzwert ebenfalls ungültig oder fehlt er, wird die Deklaration nicht ignoriert. Stattdessen wird der Anfangswert oder der geerbte Wert der Eigenschaft verwendet. Die Eigenschaft erhält also einen neuen Wert, der jedoch möglicherweise nicht dem erwarteten entspricht.

Anwendungsfälle

Die safe-area-inset-*-Werte wurden ursprünglich vom iOS-Browser bereitgestellt, damit Entwickler Inhalte in einem sicheren Bereich des Viewports platzieren können, ohne dass sie durch Display-Aussparungen oder abgerundete Ecken verdeckt werden. Mit diesen Werten lässt sich sicherstellen, dass Inhalte sichtbar bleiben. Später wurde die Funktion über ihren ursprünglichen Zweck hinaus erweitert, beispielsweise um zu verhindern, dass Gerätebenachrichtigungen Teile der App-Benutzeroberfläche verdecken.

Ein weiterer Anwendungsfall für env()-Variablen sind Progressive Web Apps (PWAs) auf Desktopgeräten, die mit der Funktion Window Controls Overlay die gesamte Fläche des Anwendungsfensters nutzen. Mithilfe der titlebar-area-*-Werte können Entwickler Elemente dort platzieren, wo sich sonst die Titelleiste befände, und verhindern, dass die Schaltflächen zur Fenstersteuerung Inhalte verdecken.

Mit den viewport-segment-*-Variablennamen können Sie Container so dimensionieren, dass sie in die verfügbaren Segmente eines Geräts mit mehreren Viewport-Segmenten passen, etwa eines faltbaren Geräts oder eines Geräts mit Scharnier. Die Ganzzahlen nach dem viewport-segment-*-Namen geben an, auf welches Segment sich die Umgebungsvariable bezieht.

Mit der Variable preferred-text-scale lassen sich Website-Text und andere UI-Elemente proportional zu den im Browser oder Betriebssystem festgelegten Schriftgrößen skalieren. Beispielsweise können Sie die Schriftgröße des Dokumenttexts als Prozentsatz festlegen, der auf der benutzerdefinierten Textskalierung basiert:

body {
  font-size: calc(100% * env(preferred-text-scale));
}

Größen lassen sich auch proportional zur Schriftgröße auf Browser- oder Betriebssystemebene festlegen, indem Sie <meta name="text-scale" content="scale"> in den <head> des Dokuments aufnehmen. Verwenden Sie nach Möglichkeit das <meta>-Tag statt env(preferred-text-scale), da es auf mehr Plattformen unterstützt wird und einfacher zu verwenden ist.

Namen mit nachfolgenden Ganzzahlen

Wenn eine Umgebungsvariable arrayartig ist, ihr Name sich also auf mehr als einen Wert beziehen kann – wie bei Geräten mit mehreren Viewport-Segmenten –, enthält der Parameter <environment-variable> sowohl den Variablennamen als auch die Indizes der Instanz, auf die sich die Funktion bezieht. Bei den viewport-segment-*-Variablen werden der Funktion env() beispielsweise zusammen mit dem Variablennamen zwei Ganzzahlen übergeben. Sie geben die Indizes des Segments an, dessen Wert zurückgegeben werden soll. Beide Ganzzahlen sind 0 oder größer. Die erste gibt den horizontalen Index des Segments an, wobei 0 für das Segment ganz links steht. Die zweite gibt den vertikalen Index an, wobei 0 für das unterste Segment steht:

• Bei einer horizontalen Anordnung nebeneinander wird das linke Segment durch 0 0 und das rechte durch 1 0 bezeichnet.
• Bei einer vertikalen Anordnung von oben nach unten wird das obere Segment durch 0 0 und das untere durch 0 1 bezeichnet.
• Bei Geräten mit mehr als zwei Segmenten können die Zahlen größer sein. Bei einem Gerät mit drei horizontalen Segmenten kann beispielsweise das mittlere Segment durch 1 0 und das rechte durch 2 0 bezeichnet werden.

Das folgende Beispiel gibt die Breite des rechten Segments auf einem faltbaren Gerät mit zwei horizontal angeordneten Segmenten zurück:

env(viewport-segment-width 1 0)

Ein vollständiges, funktionsfähiges Beispiel finden Sie in der Demo zur Viewport Segments API (Quellcode). Eine ausführliche Erklärung der Demo bietet außerdem Verwendung der Viewport Segments API.

Formale Syntax

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

<integer> = 
  <number-token>  

Beispiele

Mit env() verhindern, dass Schaltflächen durch die Geräteoberfläche verdeckt werden

Im folgenden Beispiel wird env() verwendet, um zu verhindern, dass fest positionierte Schaltflächen der App-Symbolleiste durch Gerätebenachrichtigungen am unteren Bildschirmrand verdeckt werden. Auf Desktopgeräten ist safe-area-inset-bottom gleich 0. Auf Geräten wie iOS-Geräten, die Benachrichtigungen am unteren Bildschirmrand anzeigen, enthält die Variable dagegen einen Wert, der Platz für die Benachrichtigung lässt. Dieser Wert kann für padding-bottom verwendet werden, um einen Abstand zu schaffen, der auf dem jeweiligen Gerät natürlich wirkt.

HTML

Wir verwenden einen <main>-Bereich mit einer beispielhaften Anwendung 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 CSS Flexible Box Layout erstellen wir einen Footer, der nur so hoch wie nötig ist. Der Hauptbereich mit der Anwendung füllt den übrigen Viewport aus:

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, damit der Footer am unteren Rand des Viewports haften bleibt. Anschließend fügen wir dem Footer mit der Kurzschreibweise padding Innenabstände hinzu. Zum anfänglichen unteren Innenabstand von 1em addieren wir den Wert der Umgebungsvariablen safe-area-inset-bottom. Auf Geräten, auf denen diese Variable einen positiven Wert hat, wird ein größerer schwarzer Bereich angezeigt. So bleiben die Schaltflächen im Footer stets sichtbar.

footer {
  position: sticky;
  bottom: 0;

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

Ergebnis

Einen Ersatzwert verwenden

Dieses Beispiel verwendet den optionalen zweiten Parameter von env(), der einen Ersatzwert bereitstellt, falls die Umgebungsvariable nicht verfügbar ist.

HTML

Wir fügen einen Textabsatz 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 legen eine width von 300px und einen border fest. Anschließend fügen wir mit padding Innenabstände hinzu und verwenden dabei die Funktion env() mit einem Ersatzwert für die Abstände auf jeder Seite. Für den linken Innenabstand geben wir absichtlich einen ungültigen Wert an – beachten Sie, dass Namen von Umgebungsvariablen zwischen Groß- und Kleinschreibung unterscheiden –, um die Verwendung des Ersatzwerts 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);
}

Ergebnis

Mit env() verhindern, dass Fenstersteuerungsschaltflächen Inhalte in Desktop-PWAs verdecken

Im folgenden Beispiel stellt env() sicher, dass Inhalte einer Progressive Web App auf einem Desktopgerät, die die Window Controls Overlay API verwendet, nicht durch die Fenstersteuerungsschaltflächen des Betriebssystems verdeckt werden. Die titlebar-area-*-Werte definieren ein Rechteck an der Stelle, an der normalerweise die Titelleiste angezeigt würde. Auf Geräten, die Window Controls Overlay nicht unterstützen, etwa Mobilgeräten, werden die Ersatzwerte verwendet.

So sieht eine auf einem Desktopgerät installierte PWA normalerweise aus:

Mit Window Controls Overlay erstreckt sich der Webinhalt über die gesamte Fläche des Anwendungsfensters. Die Fenstersteuerung und die PWA-Schaltflächen werden darüber eingeblendet:

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

Viewport-Segmente

Die Demo zur Viewport Segments API und der Leitfaden Verwendung der Viewport Segments API demonstrieren und erläutern die Verwendung der Funktion env() mit den viewport-segments-*-Umgebungsvariablen.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Umgebungsvariablen verwenden
• Modul CSS-Umgebungsvariablen
• var()
• Modul Benutzerdefinierte CSS-Eigenschaften für kaskadierende Variablen
• Benutzerdefinierte Eigenschaften (--*): CSS-Variablen
• <meta name="text-scale">
• Benutzerdefinierte CSS-Eigenschaften (Variablen) verwenden
• Viewport Segments API
• Das Window Controls Overlay der Titelleiste Ihrer PWA anpassen
• Inhalte in der Titelleiste anzeigen
• Aus dem Rahmen ausbrechen