env()

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨Januar 2020⁩.

* Some parts of this feature may have varying levels of support.

Die env() CSS Funktion kann verwendet werden, um den Wert einer vom User-Agent definierten Umgebungsvariable in Ihr CSS einzufügen.

Syntax

css

/* Using the four safe area inset values with no fallback values */
env(safe-area-inset-top);
env(safe-area-inset-right);
env(safe-area-inset-bottom);
env(safe-area-inset-left);

/* Using them with fallback values */
env(safe-area-inset-top, 20px);
env(safe-area-inset-right, 1em);
env(safe-area-inset-bottom, 0.5vh);
env(safe-area-inset-left, 1.4rem);

Parameter

Die Syntax der env() Funktion ist wie folgt:

env(<environment-variable-name>, <fallback>)

Der <environment-variable-name> kann einer der folgenden sein:

safe-area-inset-top, safe-area-inset-right, safe-area-inset-bottom, safe-area-inset-left: Die safe-area-inset-* Variablen sind vier Umgebungsvariablen, die ein Rechteck durch ihre oberen, rechten, unteren und linken Einfassungen vom Rand des Viewports definieren, die sicher sind, um darin Inhalte zu platzieren, ohne dass das Risiko besteht, dass sie durch die Form eines nicht-rechteckigen Displays abgeschnitten werden. Bei rechteckigen Viewports, wie einem durchschnittlichen Laptop-Monitor, ist ihr Wert null. Bei nicht-rechteckigen Displays – wie einem runden Ziffernblatt – bilden die vier vom User-Agent gesetzten Werte ein Rechteck, sodass alle Inhalte innerhalb des Rechtecks sichtbar sind.
safe-area-max-inset-top, safe-area-max-inset-right, safe-area-max-inset-bottom, safe-area-max-inset-left: Die maximalen Einfassungs-Umgebungsvariablen des sicheren Bereichs repräsentieren den statischen Maximalwert ihres dynamischen Gegenstücks safe-area-inset-*.
titlebar-area-x, titlebar-area-y, titlebar-area-width, titlebar-area-height: Die titlebar-area-* Variablen sind nützlich für PWAs, die auf Desktop-Geräten installiert sind. Wenn eine Desktop-PWA den window-controls-overlay display_override Wert verwendet, kann sie die titlebar-area-* Variablen nutzen, um sicherzustellen, dass Inhalte nicht die Fenstersteuerungsknöpfe (d.h. 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 keyboard-inset-* Variablen liefern Informationen über das Erscheinungsbild der onscreen virtuellen Tastatur. Sie definieren ein Rechteck durch ihre oberen, rechten, unteren und linken Einfassungen vom Rand des Viewports (die Breiten- und Höheneinfassungen werden aus den anderen Einfassungen berechnet). Um mehr zu erfahren, siehe die VirtualKeyboard API.

Hinweis: Wie andere CSS-Benutzerdefinierte Eigenschaftsnamen sind User-Agent-definierte Umgebungsvariablennamen groß- und kleinschreibungssensitiv.

Die env() Funktion fügt den Wert einer vom User-Agent definierten Umgebungsvariable in Ihr CSS ein, ähnlich der var() Funktion und benutzerdefinierten Eigenschaften. Der Unterschied besteht darin, dass Umgebungsvariablen vom User-Agent definiert und nicht vom Autor definiert werden und global auf ein Dokument anwendbar sind, während benutzerdefinierte Eigenschaften auf die Elemente beschränkt sind, auf denen sie deklariert werden.

Außerdem kann im Gegensatz zu benutzerdefinierten Eigenschaften, die außerhalb von Deklarationen nicht verwendet werden können, die env() Funktion anstelle von jedem Teil eines Eigenschaftswertes oder eines Deskriptors verwendet werden (z.B. in Medienabfrage-Regeln). Während sich die Spezifikation weiterentwickelt, kann sie auch an anderen Stellen wie Selektoren verwendet werden.

Ursprünglich vom iOS-Browser bereitgestellt, um Entwicklern zu ermöglichen, ihre Inhalte in einem sicheren Bereich des Viewports zu platzieren, können die in der Spezifikation definierten safe-area-inset-* Werte verwendet werden, um sicherzustellen, dass Inhalte sogar für Betrachter sichtbar sind, die nicht-rechteckige Displays verwenden.

Ein häufiges Problem, das mit env() gelöst wird, ist, dass Gerätebenachrichtigungen einen Teil der Benutzeroberfläche der App verdecken. Durch das Positionieren von fixierten Elementen mit env() kann sichergestellt werden, dass sie in einem sicheren Bereich des Viewports angezeigt werden.

Ein weiterer Anwendungsfall für env() Variablen sind Desktop-Progressive Web Apps (PWAs), die die Windows Controls Overlay-Funktion verwenden, um die gesamte Anwendungsfenster-Oberfläche auszunutzen. Mit den titlebar-area-* Werten können Entwickler Elemente dort positionieren, wo die Titelleiste gewesen wäre, und sicherstellen, dass der Inhalt die Fenstersteuerungsknöpfe nicht überlappt.

Formale Syntax

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

Verwendung

Um dem Browser mitzuteilen, den gesamten verfügbaren Platz auf dem Bildschirm zu nutzen und somit die Verwendung der env() Variablen zu ermöglichen, müssen wir einen neuen Viewport-Meta-Wert hinzufügen:

html

<meta name="viewport" content="viewport-fit=cover" />

Sie können dann env() in Ihrem CSS verwenden:

css

body {
  padding: env(safe-area-inset-top, 20px) env(safe-area-inset-right, 20px)
    env(safe-area-inset-bottom, 20px) env(safe-area-inset-left, 20px);
}

Beispiele

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

Im folgenden Beispiel wird env() verwendet, um sicherzustellen, dass die feststehenden App-Toolbar-Buttons nicht durch Gerätebenachrichtigungen am unteren Bildschirmrand verdeckt werden. Auf dem Desktop ist safe-area-inset-bottom 0. In Geräten, die Benachrichtigungen am unteren Bildschirmrand anzeigen, wie iOS, enthält es jedoch einen Wert, der Platz für die Anzeige der Benachrichtigung 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

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

css

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;
  padding: 1em 1em calc(1em + env(safe-area-inset-bottom));
  /* adds the safe-area-inset-bottom value to the initial 1em of padding.
  a larger black area will display for a device that has a positive value for this variable. */
  position: sticky;
  bottom: 0;
}

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

Verwendung des Fallback-Wertes

Im untenstehenden Beispiel wird der optionale zweite Parameter von env() verwendet, der es Ihnen ermöglicht, einen Fallback-Wert anzugeben, falls die Umgebungsvariable nicht verfügbar ist.

html

<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

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

Beispielwerte

css

/* zero for all rectangular user agents */
padding: env(safe-area-inset-bottom, 50px);

/* 50px because UA properties are case sensitive */
padding: env(Safe-area-inset-bottom, 50px);

/* as if padding: '50px 20px' were set because x is not a valid environment variable */
padding: env(x, 50px 20px);

/* ignored because '50px, 20px' is not a valid padding value and x is not a valid environment variable */
padding: env(x, 50px, 20px);

Die Syntax des Fallbacks erlaubt, wie bei benutzerdefinierten Eigenschaften, Kommata. Aber wenn der Eigenschaftswert keine Kommata unterstützt, ist der Wert ungültig.

Hinweis: User-Agent-Eigenschaften werden nicht durch die all Eigenschaft zurückgesetzt.

Verwendung von env(), um sicherzustellen, dass Inhalte nicht durch Fenstersteuerknöpfe 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 durch die Fenstersteuerknöpfe des Betriebssystems verdeckt werden. Die titlebar-area-* Werte definieren ein Rechteck, in dem normalerweise die Titelleiste angezeigt worden wäre. Auf Geräten, die die Windows Controls Overlay-Funktion nicht unterstützen, wie Mobilgeräte, werden die Fallback-Werte verwendet.

Hier ist, wie eine PWA, die auf einem Desktop-Gerät installiert ist, normalerweise aussieht:

Illustration of what a PWA installed on desktop normally looks like, with window control buttons, a title bar, and web content below that

Mit der Windows Controls Overlay-Funktion deckt der Webinhalt die gesamte Anwendungsfensterfläche ab, wobei die Fenstersteuer- und PWA-Buttons als Overlays angezeigt werden:

Illustration of what a PWA installed on desktop looks like with the Window Controls Overlay feature, with window control buttons, no title bar, and web content spanning the whole window

html

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

css

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

Hinweis: Die Verwendung von position:fixed stellt sicher, dass der Header beim Scrollen nicht mit dem Rest des Inhalts mitgeht, sondern mit den Fenstersteuerknöpfen ausgerichtet bleibt, selbst bei Geräten/Browsers, die elastisches Überscrollen (auch bekannt als Rubber Banding) unterstützen.

Spezifikationen

Specification
CSS Environment Variables Module Level 1 # env-function

Browser-Kompatibilität

Siehe auch

Help improve MDN

Learn how to contribute Diese Seite wurde automatisch aus dem Englischen übersetzt.

Übersetzung auf GitHub anzeigen • Fehler mit dieser Übersetzung melden