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 Umgebungsvariable angibt. Wenn der angegebene Name eine array-ähnliche Umgebungsvariable darstellt, wird der Name von <integer> Werten gefolgt, die die spezifische Instanz identifizieren, die der Name referenziert. Der Groß- und Kleinschreibung achtende Name der Umgebungsvariable kann einer der folgenden sein:

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

Definiert den sicheren Abstand von den oberen, rechten, unteren oder linken Einfasskanten des Viewports, wo Inhalte platziert werden können, ohne dass sie möglicherweise 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 ein Rechteck ist und keine Funktionen — wie Toolbars oder dynamische Tastaturen — den Viewport-Raum einnehmen; andernfalls ist es ein 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 safe-area-inset-* Variablen-Pendants, wenn alle dynamischen Benutzeroberflächenelemente eingezogen sind. Während sich die safe-area-inset-* Werte ändern, wenn sich der derzeit sichtbare Inhaltsbereich ändert, sind die safe-area-max-inset-* Werte konstant.

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 Variablennamen können genutzt werden, um sicherzustellen, dass Inhalte nicht die Fenstersteuerungsknöpfe (d.h. Minimieren, Maximieren und Schließen) bei progressiven Webapplikationen (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 vom Rand des Viewports und Dimensionen der virtuellen Bildschirmtastatur des Geräts. Definiert in der VirtualKeyboard API.

preferred-text-scale

Der bevorzugte Schriftmaßstab des Nutzers, eine Zahl, die in den Browser- oder Betriebssystemeinstellungen festgelegt wird. Dies kann verwendet werden, um Inhalte proportional zu den im 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 Dimensionen und Offsetpositionen spezifischer Viewport-Segmente. Auf das Schlüsselwort viewport-segment-* folgen zwei durch Leerzeichen getrennte <integer> Werte, die die horizontale und vertikale Position des Segments oder deren Indizes angeben. Die Schlüsselwörter der Viewport-Segmente sind nur definiert, wenn der Viewport aus zwei oder mehr Segmenten besteht, so wie bei klappbaren oder klappbaren Geräten.

<dashed-ident>

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

<fallback> Optional

Ein Fallback-Wert, der eingefügt wird, falls die im ersten Argument referenzierte Umgebungsvariable nicht existiert. Alles nach dem ersten Komma wird als Fallback-Wert betrachtet. Dies kann ein einzelner Wert, eine andere env() Funktion oder eine kommagetrennte Liste von Werten sein.

<declaration_value> Optional

Ein <declaration_value> ist der Standardwert des SVG-Attributes, das dynamisch gesetzt wird. Wenn der <declaration-value> weggelassen wird, repräsentiert er einen leeren Wert.

Beschreibung

Die Funktion env() wird verwendet, um den Wert einer global definierten, vom Benutzer-Agenten definierten Umgebungsvariablen in Ihr CSS einzufügen. Die env()-Funktion kann als Eigenschaftswert oder anstelle eines Teils eines Eigenschaftswertes oder Deskriptor (zum Beispiel bei Media-Query-Regeln) verwendet werden.

Die Funktion akzeptiert eine <environment-variable> als erstes Argument. Dies ist ein detailliertes <custom-ident>, das dem Namen der Umgebungsvariablen entspricht, die ersetzt werden soll, kann aber auch zusätzliche durch Leerzeichen getrennte Werte enthalten, wenn erforderlich. Zum Beispiel würde env(viewport-segment-width 0 0) die Breite des obersten oder linken Segments im Fall eines Geräts mit mehreren Viewport-Segmenten zurückgeben.

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

Die Syntax des Fallbacks ist ähnlich der Fallback-Syntax der var() Funktion, die zum Einfügen von CSS-Benutzerdefinierten Eigenschaften verwendet wird, in dem sie mehrere Kommas zulässt. 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, das keine Kommas enthält, ist ein Fallback-Wert, der Kommas enthält, nicht gültig.

Eine Eigenschaft oder ein Deskriptor, der eine syntaktisch gültige env()-Funktion enthält, wird zum Zeitpunkt des Parsens als gültig angenommen, wenn der Browser den heruntergeladenen CSS-Text zum ersten Mal liest und interpretiert. Es wird erst zur Berechnungszeit syntaxgeprüft, nachdem jede env()-Funktion durch ihren vom Browser bereitgestellten Wert (oder den Fallback-Wert, wenn die als erster Parameter übergebene Umgebungsvariable kein erkannter Umgebungsvariablenname ist) ersetzt wurde. Wenn der Wert ungültig ist und kein Fallback angegeben wird, ist die Eigenschaft oder der Deskriptor, der die env()-Funktion enthält, während der Berechnungswertzeit ungültig.

Wenn eine env()-Substitution ungültig ist und ein ungültiger Fallback enthalten ist oder der Fallback weggelassen wird, wird die Deklaration nicht ignoriert. Stattdessen wird der Initialwert oder vererbter Wert der Eigenschaft verwendet. Die Eigenschaft wird auf einen neuen Wert gesetzt, aber es kann sein, dass er nicht der erwartete ist.

Anwendungsfälle

Ursprünglich vom iOS-Browser bereitgestellt, um Entwicklern zu ermöglichen, ihren Inhalt in einem sicheren Bereich des Viewports zu platzieren und nicht von Geräteknoten oder abgerundeten Ecken verdeckt zu werden, können die safe-area-inset-* Werte verwendet werden, um sicherzustellen, dass Inhalte für Betrachter sichtbar sind. Diese Funktion wurde später über ihren ursprünglichen Zweck hinaus erweitert, um Anwendungsfälle wie das Verhindern, dass Gerätemitteilungen Teile der Benutzeroberfläche der App verdecken zu ermöglichen.

Ein weiterer Anwendungsfall für die env()-Variablen ist für Desktop Progressive Web Apps (PWAs), die die Window Controls Overlay Funktion nutzen, um die ganze Anwendungsfensteroberfläche auszunutzen. Die titlebar-area-* Werte können Entwickler verwenden, um Elemente dort zu positionieren, wo die Titelleiste gewesen wäre und sicherzustellen, dass Inhalte nicht von Fenstersteuerungsknöpfen verdeckt werden.

Die viewport-segment-* Variablennamen können verwendet werden, um Ihre Container passend in den verfügbaren Segmenten eines Multi-Viewport-Segment-Geräts wie eines klappbaren oder faltbaren Geräts zu positionieren. Die Zahlen, die dem viewport-segment-* Namen folgen, geben an, welches Segment der mehreren Segmente die Umgebungsvariable referenziert.

Die preferred-text-scale Variable kann verwendet werden, um den Text der Webseite oder andere UI-Features proportional zu den im Browser oder Betriebssystem festgelegten Schriftgrößen zu skalieren. Zum Beispiel könnten Sie die Schriftgröße des Korpus auf einen Prozentsatz basierend auf dem vom Benutzer definierten Textmaßstab setzen:

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

Größen können auch so gesetzt werden, dass sie proportional zur Schriftgröße des Browsers oder Betriebssystems sind, indem <meta name="text-scale" content="scale"> im Dokument <head> eingefügt wird. Das <meta>-Tag sollte gegenüber dem env(preferred-text-scale) bevorzugt verwendet werden, da das <meta>-Tag über eine größere Plattformreichweite unterstützt wird und zudem einfacher zu verwenden ist.

Namen gefolgt von ganzen Zahlen

Wenn die Umgebungsvariable array-ähnlich ist, was bedeutet, dass der Name mehr als einmal einen Wert referenzieren kann, wie es bei Geräten mit mehreren Viewport-Segmenten der Fall ist, beinhaltet der <environment-variable>-Parameter sowohl den Namen der Variablen als auch die Indizes der spezifischen Instanz der Variable, die die Funktion referenziert. Zum Beispiel, im Fall der viewport-segment-* Variablen, werden die Variablennamen an die env()-Funktion zusammen mit zwei Ganzenzahlen ü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 repräsentiert den horizontalen Index des Segments, wobei 0 das linksmöglichste Segment ist, und der zweite Wert repräsentiert den vertikalen Index des Segments, wobei 0 das unterste Segment repräsentiert:

• In einem horizontalen Nebeneinander-Layout wird das linke Segment durch 0 0 repräsentiert, und das rechte Segment durch 1 0.
• In einem vertikalen Oben-nach-Unten-Layout wird das obere Segment durch 0 0 repräsentiert, und das untere Segment durch 0 1.
• Bei Geräten mit mehr als zwei Segmenten können die Zahlen größer sein. Zum Beispiel kann ein Gerät mit drei horizontalen Segmenten das mittlere Segment durch 1 0 und das rechte Segment durch 2 0 repräsentieren.

Zum Beispiel gibt das folgende Beispiel die Breite des rechten Segments auf einem faltbaren Gerät mit zwei Segmenten zurück, bei dem die Segmente horizontal orientiert sind:

env(viewport-segment-width 1 0)

Sehen Sie sich die Viewport-Segment-API-Demo für eine vollständige funktionierende Demo (Quellcode) an. Schauen Sie sich auch Verwendung der Viewport-Segmente-API für eine vollständige Erläuterung der Demo an.

Formale Syntax

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

<integer> = 
  <number-token>  

Beispiele

Verwendung von env() zur Sicherstellung, dass Schaltflächen nicht von Geräte-UI verdeckt werden

Im folgenden Beispiel wird env() verwendet, um sicherzustellen, dass die fixen App-Toolbar-Schaltflächen nicht von Gerätemitteilungen, die am unteren Bildschirmrand erscheinen, verdeckt werden. Auf dem Desktop ist safe-area-inset-bottom 0. In Geräten, die Mitteilungen am unteren Bildschirmrand anzeigen, wie iOS, enthält er jedoch einen Wert, der Platz für die Anzeige der Mitteilung lässt. Dies kann dann im Wert für padding-bottom verwendet werden, um eine Lücke zu schaffen, die auf diesem Gerät natürlich erscheint.

HTML

Wir haben einen <main> Abschnitt, der eine fiktive Anwendung enthält, und einen <footer>, der zwei <button> Elemente enthält:

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

CSS

Mit CSS flexibler Box-Layout erstellen wir einen Footer, der nur so hoch ist, wie er sein muss, während der Hauptabschnitt mit der Anwendung den Rest des Viewports 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 Viewports zu fixieren. Wir verwenden das padding Shorthand, um dem Footer Padding hinzuzufügen. Wir fügen den Wert der safe-area-inset-bottom Umgebungsvariable zu einem anfänglichen 1em unteren Padding 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-Wertes

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 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 eine border. Dann fügen wir padding hinzu, wobei wir die env() Funktion mit einem Fallback für die Größe des Paddings auf jeder Seite verwenden. Absichtlich setzen wir einen ungültigen Wert für das linke Padding (denken Sie daran, dass Umgebungsvariablennamen groß- und kleinschreibungssensitiv sind), um die Verwendung des Fallback-Wertes 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() zur Sicherstellung, dass Inhalte nicht von Fenstersteuerungsknöpfen in Desktop-PWAs verdeckt werden

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

So sieht eine PWA, die auf einem Desktopgerät installiert ist, normalerweise aus:

Mit der Window Controls Overlay-Funktion decken die Webinhalte die gesamte Anwendungsfensteroberfläche ab, und die Fenstersteuerungsknöpfe und 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 Viewport Segment API Demo und der Verwendung der Viewport Segments API Leitfaden bietet eine Demonstration und Erklärung der Verwendung der Funktion env() mit den viewport-segments-* Umgebungsvariablen.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Verwendung von Umgebungsvariablen
• Modul CSS-Umgebungsvariablen
• var()
• Modul CSS-Benutzerdefinierte Eigenschaften für kaskadierende Variablen
• Benutzerdefinierte Eigenschaften (--*): CSS-Variablen
• <meta name="text-scale">
• Verwendung von CSS-Benutzerdefinierten Eigenschaften (Variablen)
• Viewport Segments API
• Anpassen des Fenstersteuerungs-Overlays Ihrer PWA-Titelleiste
• Inhalte in der Titelleiste anzeigen
• Ausbrechen aus dem Rahmen