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 Umgebungsvariable angibt. Wenn der angegebene Name eine arrayähnliche Umgebungsvariable darstellt, folgt auf den Namen ein <integer>-Wert, der die spezifische Instanz identifiziert, auf die sich der Name bezieht. Der groß-/kleinschreibungssensitive Name der Umgebungsvariable 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 Innenrand des Viewports, der definiert, wo Inhalte sicher platziert 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 der Viewport rechteckig ist und keine Funktionen — wie Werkzeugleisten oder dynamische Tastaturen — Platz im Viewport beanspruchen; 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 ihrer dynamischen Entsprechungen der Variablen safe-area-inset-*, wenn alle dynamischen Benutzeroberflächenfunktionen ausgeblendet sind. Während sich die Werte von safe-area-inset-* ändern, wenn sich der aktuell sichtbare Inhaltsbereich ändert, sind die Werte von safe-area-max-inset-* Konstanten.

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

Die Abmessungen eines sichtbaren Bereichs titlebar-area-*. Diese Variablen sind verfügbar, wenn das Manifestfeld display_override mit window-controls-overlay verwendet wird. Die Werte der Variablen können verwendet werden, um sicherzustellen, dass sich Inhalte bei auf Desktopgeräten installierten Progressive Web Apps (PWAs) nicht mit Fensterschaltflächen (also Minimieren, Maximieren und Schließen) überschneiden.

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

Die Innenabstände vom Rand des Viewports sowie die Abmessungen der virtuellen Bildschirmtastatur des Geräts. Definiert in der VirtualKeyboard API.

preferred-text-scale

Der bevorzugte Schriftartskalierungsfaktor des Benutzers, eine in den Einstellungen des Browsers oder Betriebssystems festgelegte Zahl. Dieser kann verwendet werden, um Inhalte proportional zu den vom Browser oder Betriebssystem festgelegten Schriftgrößen zu skalieren.

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 Indizes des Segments angeben. Die Viewport-Segment-Schlüsselwörter werden nur definiert, wenn der Viewport aus zwei oder mehr Segmenten besteht, wie bei faltbaren Geräten oder Geräten mit Scharnier.

<dashed-ident>

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

<fallback> Optional

Ein Fallback-Wert, der eingefügt wird, wenn die im ersten Argument referenzierte Umgebungsvariable nicht existiert. Alles nach dem ersten Komma wird als Fallback-Wert betrachtet. 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 dynamisch gesetzten SVG-Attributs. Wenn <declaration-value> weggelassen wird, stellt es einen leeren Wert dar.

Beschreibung

Die Funktion env() wird verwendet, um den Wert einer global gültigen, vom User-Agent definierten Umgebungsvariable in Ihr CSS einzufügen. Die Funktion env() kann als Eigenschaftswert oder anstelle eines beliebigen Teils eines Eigenschaftswerts oder Deskriptors verwendet werden, beispielsweise in Media-Query-Regeln.

Die Funktion akzeptiert als erstes Argument eine <environment-variable>. Dies ist ein groß-/kleinschreibungssensitiver <custom-ident>, der dem Namen der Umgebungsvariable entspricht, die ersetzt werden soll, kann jedoch bei Bedarf auch zusätzliche durch Leerzeichen getrennte Werte enthalten. Beispielsweise würde env(viewport-segment-width 0 0) bei einem Gerät mit mehreren Viewport-Segmenten die Breite des oberen oder linken Segments zurückgeben.

Das zweite Argument ist, sofern angegeben, der Fallback-Wert, der verwendet wird, wenn die im ersten Argument referenzierte Umgebungsvariable nicht unterstützt wird oder nicht existiert. Der Fallback kann eine weitere Umgebungsvariable sein, auch mit einem eigenen Fallback.

Die Syntax des Fallbacks ähnelt der Fallback-Syntax der Funktion var(), die zum Einfügen von benutzerdefinierten CSS-Eigenschaften verwendet wird, da sie mehrere Kommas zulässt. Alles zwischen dem ersten Komma und dem Ende der Funktion wird als Fallback-Wert angesehen. Wenn die Funktion env() jedoch innerhalb eines Eigenschaftswerts oder Deskriptors verwendet wird, der keine Kommas enthält, ist ein Fallback-Wert mit Kommas nicht gültig.

Eine Eigenschaft oder ein Deskriptor, die beziehungsweise der eine syntaktisch gültige Funktion env() enthält, wird zur Parse-Zeit, wenn der Browser den heruntergeladenen CSS-Text erstmals liest und interpretiert, als gültig angenommen. Die Syntax wird erst zur Berechnungszeit geprüft, nachdem jede Funktion env() durch ihren vom Browser bereitgestellten Wert ersetzt wurde — oder durch den Fallback-Wert, wenn die als erster Parameter übergebene Umgebungsvariable kein erkannter Name einer Umgebungsvariable ist. Wenn der Wert ungültig ist und kein Fallback bereitgestellt wird, ist die Eigenschaft oder der Deskriptor, die beziehungsweise der die Funktion env() enthält, zur Zeit der Berechnung des Eigenschaftswerts ungültig.

Wenn eine env()-Ersetzung ungültig ist und ein ungültiger Fallback enthalten ist oder der Fallback weggelassen wird, wird die Deklaration nicht ignoriert. Stattdessen wird der initiale oder geerbte Wert der Eigenschaft verwendet. Der Eigenschaft wird ein neuer Wert zugewiesen, dieser entspricht jedoch möglicherweise nicht dem erwarteten Wert.

Anwendungsfälle

Die Werte safe-area-inset-* wurden ursprünglich vom iOS-Browser bereitgestellt, damit Entwickler ihre Inhalte in einem sicheren Bereich des Viewports platzieren können und diese nicht durch Gerätekerben oder abgerundete Ecken verdeckt werden. Sie können dazu verwendet werden, sicherzustellen, dass Inhalte für Betrachter sichtbar sind. Diese Funktion wurde später über ihren ursprünglichen Zweck hinaus erweitert, um Anwendungsfälle zu ermöglichen, beispielsweise das Verhindern, dass Gerätebenachrichtigungen Teile der Anwendungsbenutzeroberfläche verdecken.

Ein weiterer Anwendungsfall für env()-Variablen sind Desktop-Progressive Web Apps (PWAs), die die Funktion Window Controls Overlay verwenden, um die gesamte Oberfläche des Anwendungsfensters zu nutzen. Mithilfe der titlebar-area-*-Werte können Entwickler Elemente dort positionieren, wo sich ansonsten die Titelleiste befinden würde, und sicherstellen, dass Inhalte nicht durch Fensterschaltflächen verdeckt werden.

Die Variablennamen viewport-segment-* können verwendet werden, um Ihre Container so festzulegen, dass sie sauber in die verfügbaren Segmente eines Geräts mit mehreren Viewport-Segmenten passen, beispielsweise eines Geräts mit Scharnier oder eines faltbaren Geräts. Die auf den Namen viewport-segment-* folgenden Ganzzahlen geben an, auf welches der mehreren Segmente sich die Umgebungsvariable bezieht.

Die Variable preferred-text-scale kann verwendet werden, um Website-Text oder andere UI-Funktionen proportional zu den vom Browser oder Betriebssystem festgelegten Schriftgrößen zu skalieren. Beispielsweise könnten Sie die Schriftgröße des Body als Prozentsatz festlegen, der auf der benutzerdefinierten Textskalierung basiert:

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

Größen können auch proportional zur Schriftgröße des Browsers oder Betriebssystems festgelegt werden, indem <meta name="text-scale" content="scale"> in den <head> des Dokuments eingefügt wird. Das Tag <meta> sollte nach Möglichkeit anstelle von env(preferred-text-scale) verwendet werden, da das Tag <meta> auf einer größeren Bandbreite von Plattformen unterstützt wird und außerdem einfacher zu verwenden ist.

Namen mit nachfolgenden Ganzzahlen

Wenn die Umgebungsvariable arrayähnlich ist, das heißt, wenn sich der Name auf mehr als einen Wert beziehen kann, wie bei Geräten mit mehreren Viewport-Segmenten, enthält der Parameter <environment-variable> sowohl den Namen der Variablen als auch die Indizes der spezifischen Instanz der Variablen, auf die sich die Funktion bezieht. Beispielsweise werden bei den Variablen viewport-segment-* die Variablennamen zusammen mit zwei Ganzzahlen an die Funktion env() übergeben, die die Indizes des Segments angeben, für das der Wert zurückgegeben werden soll. Diese Werte sind beide Ganzzahlen von 0 oder größer. Die erste Ganzzahl stellt den horizontalen Index des Segments dar, wobei 0 das am weitesten links liegende Segment ist, und der zweite Wert stellt den vertikalen Index des Segments dar, wobei 0 das unterste Segment darstellt:

• In einem horizontalen Nebeneinander-Layout wird das linke Segment durch 0 0 und das rechte Segment durch 1 0 dargestellt.
• In einem vertikalen Layout von oben nach unten wird das obere Segment durch 0 0 und das untere Segment durch 0 1 dargestellt.
• 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 Segment durch 2 0 dargestellt werden.

Das Folgende gibt beispielsweise die Breite des rechten Segments auf einem faltbaren Gerät mit zwei horizontal ausgerichteten Segmenten zurück:

env(viewport-segment-width 1 0)

Eine vollständig funktionsfähige Demo finden Sie in der Viewport-Segment-API-Demo (Quellcode). Lesen Sie auch Using the Viewport Segments API für eine vollständige Erklärung der Demo.

Formale Syntax

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

<integer> = 
  <number-token>  

Beispiele

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

Im folgenden Beispiel wird env() verwendet, um sicherzustellen, dass feste Schaltflächen der Anwendungswerkzeugleiste nicht durch Gerätebenachrichtigungen verdeckt werden, die am unteren Bildschirmrand erscheinen. Auf dem Desktop ist safe-area-inset-bottom gleich 0. Auf Geräten, die Benachrichtigungen am unteren Bildschirmrand anzeigen, wie etwa iOS, enthält es jedoch einen Wert, der Platz für die Anzeige der Benachrichtigung lässt. Dieser kann dann im Wert für padding-bottom verwendet werden, um einen Abstand zu schaffen, der auf diesem Gerät natürlich wirkt.

HTML

Wir haben einen <main>-Abschnitt mit einer simulierten Anwendung und ein <footer>, das zwei <button>-Elemente enthält:

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

CSS

Mithilfe von CSS Flexible Box Layout erstellen wir einen Footer, der nur so hoch ist, wie erforderlich, während der die Anwendung enthaltende Hauptabschnitt den restlichen Viewport 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, damit der Footer am unteren Rand des Viewports bleibt. Anschließend verwenden wir die Kurzform padding, um dem Footer Innenabstand hinzuzufügen. Wir fügen den Wert der Umgebungsvariable safe-area-inset-bottom zu einem anfänglichen unteren Innenabstand von 1em hinzu. Auf Geräten mit einem positiven Wert für diese Variable wird ein größerer schwarzer Bereich angezeigt, wodurch sichergestellt wird, 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 verwendet den optionalen zweiten Parameter von env(), der einen Fallback-Wert bereitstellt, 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 setzen eine width von 300px und einen border. Anschließend fügen wir padding hinzu und verwenden dabei die Funktion env() mit einem Fallback für die Größe des Innenabstands auf jeder Seite. Wir setzen absichtlich einen ungültigen Wert für den linken Innenabstand — beachten Sie, dass bei Namen von Umgebungsvariablen die Groß- und Kleinschreibung beachtet wird —, 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 in Desktop-PWAs nicht durch Fensterschaltflächen verdeckt werden

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

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

Mit der Funktion Window Controls Overlay bedecken die Webinhalte die gesamte Oberfläche des Anwendungsfensters, während die Fensterschaltflächen und PWA-Schaltflächen als Overlays 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);
}

Viewport-Segmente

Die Viewport-Segment-API-Demo und der Leitfaden Using the Viewport Segments API bieten eine Demonstration und Erklärung zur Verwendung der Funktion env() mit den Umgebungsvariablen viewport-segments-*.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Verwendung von Umgebungsvariablen
• Modul CSS-Umgebungsvariablen
• var()
• Modul benutzerdefinierte CSS-Eigenschaften für kaskadierende Variablen
• Benutzerdefinierte Eigenschaften (--*): CSS-Variablen
• <meta name="text-scale">
• Verwendung benutzerdefinierter CSS-Eigenschaften (Variablen)
• Viewport Segments API
• Passen Sie das Fenstersteuerungs-Overlay der Titelleiste Ihrer PWA an
• Inhalte in der Titelleiste anzeigen
• Breaking Out of the Box