CSS-Funktion env()

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 darauf <integer>-Werte, die die jeweilige Instanz kennzeichnen. 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 Sicherheitsabstand 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 wie 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 der Wert window-controls-overlay verwendet wird. Mithilfe der Variablenwerte lässt sich verhindern, dass Inhalte installierter Progressive Web Apps (PWAs) auf Desktopgeräten die Schaltflächen zur Fenstersteuerung (Minimieren, Maximieren und Schließen) überdecken.

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, der 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

Mit der Funktion env() wird der Wert einer global verfügbaren, vom User-Agent definierten Umgebungsvariablen in CSS eingefügt. env() kann als Eigenschaftswert oder anstelle eines beliebigen Teils eines Eigenschaftswerts oder Deskriptors verwendet werden, beispielsweise in Medienabfrageregeln.

Die Funktion akzeptiert als erstes Argument ein <environment-variable>. Dies ist ein <custom-ident>, bei dem zwischen Groß- und Kleinschreibung unterschieden wird und das dem zu ersetzenden Namen der Umgebungsvariablen entspricht. Bei Bedarf können zusätzliche, durch Leerzeichen getrennte Werte folgen. Beispielsweise würde env(viewport-segment-width 0 0) auf einem Gerät mit mehreren Viewport-Segmenten die Breite des oberen beziehungsweise linken Segments zurückgeben.

Das zweite Argument ist, sofern angegeben, der Ersatzwert. Er wird verwendet, wenn die im ersten Argument angegebene Umgebungsvariable nicht unterstützt wird oder nicht existiert. Als Ersatzwert kann auch eine andere Umgebungsvariable dienen, die wiederum einen eigenen Ersatzwert haben kann.

Die Syntax des Ersatzwerts ähnelt der Ersatzwertsyntax 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. Wird env() jedoch innerhalb eines Eigenschaftswerts oder Deskriptors verwendet, 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 des Werts 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 resultierende Wert ungültig und wurde kein Ersatzwert angegeben, ist die Eigenschaft oder der Deskriptor mit env() zum Zeitpunkt der Wertberechnung ungültig.

Wenn die Ersetzung durch env() ungültig ist und der angegebene Ersatzwert ebenfalls ungültig ist oder fehlt, wird die Deklaration nicht ignoriert. Stattdessen wird der Anfangswert oder der geerbte Wert der Eigenschaft verwendet. Die Eigenschaft erhält damit 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, wo sie nicht durch Displayaussparungen oder abgerundete Ecken verdeckt werden. Sie helfen sicherzustellen, dass Inhalte sichtbar bleiben. Später wurde diese 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 positionieren, wo sich sonst die Titelleiste befände, und verhindern, dass 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, beispielsweise 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 können Sie Website-Text oder andere Elemente der Benutzeroberfläche proportional zu den im Browser oder Betriebssystem festgelegten Schriftgrößen skalieren. Beispielsweise können Sie die Schriftgröße von body als Prozentsatz festlegen, der auf dem vom Benutzer definierten Textskalierungsfaktor basiert:

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

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

Namen mit nachfolgenden Ganzzahlen

Wenn eine Umgebungsvariable arrayartig ist und ihr Name somit auf mehrere Werte verweisen kann – etwa bei Geräten mit mehreren Viewport-Segmenten –, enthält der Parameter <environment-variable> sowohl den Variablennamen als auch die Indizes der jeweiligen Instanz. Bei den viewport-segment-*-Variablen werden der Name und zwei Ganzzahlen an env() übergeben. Diese geben die Indizes des Segments an, dessen Wert zurückgegeben werden soll. Beide Ganzzahlen sind 0 oder größer. Die erste bezeichnet den horizontalen Index des Segments, wobei 0 für das Segment ganz links steht. Die zweite bezeichnet den vertikalen Index, 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. Beispielsweise kann bei einem Gerät mit drei horizontalen Segmenten das mittlere Segment durch 1 0 und das rechte durch 2 0 bezeichnet werden.

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

env(viewport-segment-width 1 0)

Eine vollständige, lauffähige Demonstration finden Sie in der Demo zur Viewport Segments API (Quellcode). Eine ausführliche Erläuterung 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 Geräteelemente Schaltflächen verdecken

Im folgenden Beispiel sorgt env() dafür, dass fest positionierte Schaltflächen einer App-Symbolleiste nicht 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 zum jeweiligen Gerät passenden Abstand zu schaffen.

HTML

Wir verwenden einen <main>-Abschnitt mit einer Beispielanwendung und ein <footer>-Element 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 Hauptabschnitt 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;
}

Mit position: sticky halten wir den Footer am unteren Rand des Viewports. Anschließend fügen wir ihm mit der Kurzschreibweise padding einen Innenabstand hinzu. Zum anfänglichen unteren Innenabstand von 1em addieren wir den Wert der Umgebungsvariablen safe-area-inset-bottom. Auf Geräten, für die diese Variable einen positiven Wert hat, erscheint dadurch ein größerer schwarzer Bereich, sodass die Schaltflächen im Footer nicht verdeckt werden.

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(). Er stellt einen Ersatzwert bereit, falls die Umgebungsvariable nicht verfügbar ist.

HTML

Wir fügen einen Textabsatz ein:

<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 eine border fest. Anschließend fügen wir padding hinzu und verwenden env() mit einem Ersatzwert für den Innenabstand auf jeder Seite. Für den linken Innenabstand geben wir absichtlich einen ungültigen Wert an – beachten Sie, dass bei Namen von Umgebungsvariablen zwischen Groß- und Kleinschreibung unterschieden wird –, 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 sorgt env() dafür, dass Inhalte einer Progressive Web App auf Desktopgeräten, die die Window Controls Overlay API verwendet, nicht durch die Schaltflächen zur Fenstersteuerung 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 App-Fensters. Die Fenstersteuerung und die PWA-Schaltflächen werden als Overlays angezeigt:

<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 von 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
• Überlagerung der Fenstersteuerung in der Titelleiste Ihrer PWA anpassen
• Inhalte in der Titelleiste anzeigen
• Breaking Out of the Box