Verwendung von CSS-Benutzerdefinierten Eigenschaften (Variablen)

Deklarieren von benutzerdefinierten Eigenschaften

In CSS können Sie eine benutzerdefinierte Eigenschaft deklarieren, indem Sie zwei Bindestriche als Präfix für den Eigenschaftsnamen verwenden oder die @property-At-Regel nutzen. Die folgenden Abschnitte beschreiben, wie Sie diese beiden Methoden verwenden.

Mit einem Präfix von zwei Bindestrichen (--)

Eine benutzerdefinierte Eigenschaft, die mit zwei Bindestrichen beginnt, beginnt mit --, gefolgt vom Eigenschaftsnamen (z.B. --my-property) und einem Eigenschaftswert, der ein beliebiger gültiger CSS-Wert sein kann. Wie jede andere Eigenschaft wird diese innerhalb eines Regelsatzes geschrieben. Das folgende Beispiel zeigt, wie man eine benutzerdefinierte Eigenschaft --main-bg-color erstellt und den Wert brown verwendet:

section {
  --main-bg-color: brown;
}

Der dem Regelsatz gegebene Selektor (z.B. <section>-Elemente im obigen Beispiel) definiert den Bereich, in dem die benutzerdefinierte Eigenschaft verwendet werden kann. Aus diesem Grund ist es eine gängige Praxis, benutzerdefinierte Eigenschaften auf der :root-Pseudoklasse zu definieren, so dass sie global referenziert werden kann:

:root {
  --main-bg-color: brown;
}

Das muss nicht immer der Fall sein: Sie haben möglicherweise einen guten Grund, den Anwendungsbereich Ihrer benutzerdefinierten Eigenschaften zu begrenzen.

Verwendung der @property-At-Regel

Die @property-At-Regel ermöglicht es Ihnen, die Definition einer benutzerdefinierten Eigenschaft ausdrücklicher zu gestalten, indem Sie die Möglichkeit haben, einen Typ mit der Eigenschaft zu assoziieren, Standardwerte festzulegen und die Vererbung zu steuern. Das folgende Beispiel erstellt eine benutzerdefinierte Eigenschaft namens --logo-color, die einen <color> erwartet:

@property --logo-color {
  syntax: "<color>";
  inherits: false;
  initial-value: #c0ffee;
}

Wenn Sie benutzerdefinierte Eigenschaften in JavaScript definieren oder verwenden möchten, anstatt direkt in CSS, gibt es eine entsprechende API für diesen Zweck. Sie können lesen, wie dies auf der Seite CSS Properties and Values API funktioniert.

Referenzieren von benutzerdefinierten Eigenschaften mit var()

Unabhängig davon, welche Methode Sie wählen, um eine benutzerdefinierte Eigenschaft zu definieren, verwenden Sie sie, indem Sie die Eigenschaft in einer var()-Funktion anstelle eines Standard-Eigenschaftswertes referenzieren:

details {
  background-color: var(--main-bg-color);
}

Erste Schritte mit benutzerdefinierten Eigenschaften

Lassen Sie uns mit etwas HTML beginnen, auf das wir einige Stile anwenden möchten. Es gibt ein <div>, das als Container fungiert und einige Kindelemente enthält, einige mit verschachtelten Elementen:

<div class="container">
  <div class="one">
    <p>One</p>
  </div>
  <div class="two">
    <p>Two</p>
    <div class="three">
      <p>Three</p>
    </div>
  </div>
  <input class="four" placeholder="Four" />
  <textarea class="five">Five</textarea>
</div>

Wir werden das folgende CSS verwenden, um einige verschiedene Elemente basierend auf ihren Klassen zu stylen (einige Layout-Regeln werden unten nicht gezeigt, damit wir uns auf Farben konzentrieren können). Abhängig von ihren Klassen geben wir Elementen teal oder pink Hintergrundfarben:

/* Set fonts, borders and padding */
body,
textarea,
::placeholder {
  font-family: sans-serif;
  color: white;
}

div,
input,
textarea {
  border: 2px black solid;
  padding: 4px;
  margin: 4px;
}

.container {
  display: grid;
  gap: 10px;
}

/* For each class, set some colors */
.one {
  background-color: teal;
}

.two {
  color: black;
  background-color: pink;
}

.three {
  color: white;
  background-color: teal;
}

.four {
  background-color: teal;
}

.five {
  background-color: teal;
}

Dies ergibt das folgende Ergebnis:

Es gibt eine Gelegenheit, benutzerdefinierte Eigenschaften zu verwenden, um repetitive Werte über diese Regeln hinweg zu ersetzen. Nach der Definition von --main-bg-color im .container-Bereich und der Referenzierung seines Wertes an mehreren Stellen sehen die aktualisierten Stile so aus:

/* Define --main-bg-color here */
.container {
  --main-bg-color: teal;
}

/* For each class, set some colors */
.one {
  background-color: var(--main-bg-color);
}

.two {
  color: black;
  background-color: pink;
}

.three {
  color: white;
  background-color: var(--main-bg-color);
}

.four {
  background-color: var(--main-bg-color);
}

.five {
  background-color: var(--main-bg-color);
}

Verwendung der :root Pseudoklasse

Für einige CSS-Deklarationen ist es möglich, diese höher in der Kaskade zu deklarieren und CSS-Vererbung das Problem lösen zu lassen. Für nicht-triviale Projekte ist dies jedoch nicht immer möglich. Durch das Deklarieren einer benutzerdefinierten Eigenschaft auf der :root-Pseudoklasse und deren Verwendung bei Bedarf im gesamten Dokument kann ein CSS-Autor die Notwendigkeit für Wiederholungen reduzieren:

/* Define --main-bg-color here */
:root {
  --main-bg-color: teal;
}

/* For each class, set some colors */
.one,
.three,
.four,
.five {
  background-color: var(--main-bg-color);
}

.two {
  color: black;
  background-color: pink;
}

Dies führt zum gleichen Ergebnis wie das vorherige Beispiel, erlaubt jedoch eine kanonische Deklaration des gewünschten Eigenschaftswerts (--main-bg-color: teal;), was sehr nützlich ist, wenn Sie den Wert später im gesamten Projekt ändern möchten.

Vererbung von benutzerdefinierten Eigenschaften

Eine benutzerdefinierte Eigenschaft, die mit zwei Bindestrichen -- anstelle von @property definiert wird, erbt immer den Wert ihres Elternteils. Dies wird im folgenden Beispiel demonstriert:

<div class="one">
  <p>One</p>
  <div class="two">
    <p>Two</p>
    <div class="three"><p>Three</p></div>
    <div class="four"><p>Four</p></div>
  </div>
</div>

div {
  color: black;
  font-family: sans-serif;
  width: 75%;
  height: 80%;
  margin: 4px;
  border: 2px black solid;
  display: inline-block;
}

p {
  margin: 0;
}

.one {
  height: 250px;
}

.two {
  color: white;
  height: 80%;
}

.three {
  color: black;
  height: 40%;
}

.four {
  color: white;
  height: 40%;
}

div {
  background-color: var(--box-color);
}

.two {
  --box-color: teal;
}

.three {
  --box-color: pink;
}

Die Ergebnisse von var(--box-color) je nach Vererbung sind wie folgt:

• class="one": ungültiger Wert, was der Standardwert einer auf diese Weise definierten benutzerdefinierten Eigenschaft ist
• class="two": teal
• class="three": pink
• class="four": teal (vom Elternteil geerbt)

Ein Aspekt der benutzerdefinierten Eigenschaften, den die obigen Beispiele demonstrieren, ist, dass sie sich nicht genau wie Variablen in anderen Programmiersprachen verhalten. Der Wert wird dort berechnet, wo er benötigt wird, und nicht gespeichert und an anderen Stellen eines Stylesheets wiederverwendet. Zum Beispiel kann man nicht den Wert einer Eigenschaft setzen und erwarten, den Wert in der Regel eines Geschwisters oder Nachfahrens abzurufen. Die Eigenschaft wird nur für den übereinstimmenden Selektor und dessen Nachfahren gesetzt.

Verwendung von @property, um die Vererbung zu steuern

Die @property-At-Regel lässt Sie ausdrücklich angeben, ob die Eigenschaft vererbt wird oder nicht. Das folgende Beispiel erstellt eine benutzerdefinierte Eigenschaft mit der @property-At-Regel. Die Vererbung ist deaktiviert, es ist ein <color>-Datentyp definiert, und ein Anfangswert von teal.

Das Elternelement setzt --box-color auf einen Wert von green und verwendet --box-color als Wert für seine Hintergrundfarbe. Das Kindelement verwendet ebenfalls background-color: var(--box-color), und wir würden erwarten, dass es die Farbe green hat, wenn die Vererbung aktiviert wäre (oder wenn es mit der Doppelstrich-Syntax definiert wurde).

<div class="parent">
  <p>Parent element</p>
  <div class="child">
    <p>Child element with inheritance disabled for --box-color.</p>
  </div>
</div>

div {
  color: white;
  font-family: sans-serif;
  width: 200px;
  height: 200px;
  margin: 4px;
  padding: 8px;
  border: 2px black solid;
  display: inline-block;
}

@property --box-color {
  syntax: "<color>";
  inherits: false;
  initial-value: teal;
}

.parent {
  --box-color: green;
  background-color: var(--box-color);
}

.child {
  width: 80%;
  height: 40%;
  background-color: var(--box-color);
}

Da inherits: false; in der At-Regel gesetzt ist und ein Wert für die Eigenschaft --box-color nicht im .child-Bereich deklariert ist, wird der Anfangswert von teal anstelle von green verwendet, das vom Elternteil geerbt worden wäre:

Rückfallwerte für benutzerdefinierte Eigenschaften

Sie können Rückfallwerte für benutzerdefinierte Eigenschaften mithilfe der var()-Funktion und des Anfangswerts der @property-At-Regel definieren.

Definition von Rückfallwerten in der var()-Funktion

Mit der var()-Funktion können Sie mehrere Rückfallwerte definieren, wenn die gegebene Variable noch nicht definiert ist; dies kann nützlich sein, wenn Sie mit Benutzerdefinierten Elementen und Shadow DOM arbeiten.

Das erste Argument der Funktion ist der Name der benutzerdefinierten Eigenschaft. Das zweite Argument der Funktion ist ein optionaler Rückfallwert, der als Ersatzwert verwendet wird, wenn die referenzierte benutzerdefinierte Eigenschaft ungültig ist. Die Funktion akzeptiert zwei Parameter, wobei alles nach dem ersten Komma als zweiter Parameter zugewiesen wird. Wenn der zweite Parameter ungültig ist, schlägt der Rückfall fehl. Zum Beispiel:

.one {
  /* Red if --my-var is not defined */
  color: var(--my-var, red);
}

.two {
  /* pink if --my-var and --my-background are not defined */
  color: var(--my-var, var(--my-background, pink));
}

.three {
  /* Invalid: "--my-background, pink" */
  color: var(--my-var, --my-background, pink);
}

Einen benutzerdefinierten Eigenschaft als Rückfallwert zu verwenden, wie im zweiten obigen Beispiel gezeigt (var(--my-var, var(--my-background, pink))), ist der richtige Weg, um mehr als einen Rückfall mit var() bereitzustellen. Sie sollten sich jedoch der Auswirkungen auf die Leistung dieser Methode bewusst sein, da es mehr Zeit in Anspruch nimmt, durch die verschachtelten Variablen zu parsen.

Rückfälle mit dem @property-Initialwert

Neben der Verwendung von var() kann der in der @property-At-Regel definierte initial-value als Rückfallmechanismus verwendet werden. Tatsächlich haben wir dies bereits im Abschnitt @property-Vererbung gesehen.

Im folgenden Beispiel wird ein Anfangswert von --box-color auf teal mithilfe der @property-At-Regel festgelegt. Im Regelsatz nach der At-Regel möchten wir --box-color auf pink setzen, aber es gibt einen Tippfehler im Eigenschaftsnamen. Dasselbe gilt für das dritte <div>, wo wir 2rem für die benutzerdefinierte Eigenschaft verwendet haben, die einen gültigen <color>-Wert erwartet. Sowohl 2rem als auch peenk sind ungültige Farbwerte, daher wird der Anfangswert von teal angewendet:

@property --box-color {
  syntax: "<color>";
  initial-value: teal;
  inherits: false;
}

.one {
  --box-color: pink;
  background-color: var(--box-color);
}

.two {
  --box-color: peenk;
  background-color: var(--box-color);
}

.three {
  --box-color: 2rem;
  background-color: var(--box-color);
}

div {
  color: white;
  font-family: sans-serif;
  width: 100px;
  height: 100px;
  margin: 4px;
  padding: 8px;
  border: 2px black solid;
  display: inline-block;
}

.one {
  color: black;
}

<div class="one">
  <p>One</p>
</div>
<div class="two">
  <p>Two.</p>
</div>
<div class="three">
  <p>Three.</p>
</div>

Ungültige benutzerdefinierte Eigenschaften

Jede CSS-Eigenschaft kann einem definierten Satz von Werten zugewiesen werden. Wenn Sie versuchen, einer Eigenschaft einen Wert zuzuweisen, der außerhalb ihres Satzes gültiger Werte liegt, wird er als ungültig betrachtet.

Wenn der Browser auf einen ungültigen Wert für eine reguläre CSS-Eigenschaft stößt (zum Beispiel ein Wert von 16px für die color-Eigenschaft), verwirft er die Deklaration, und die Elemente erhalten die Werte, die sie hätten, wenn die Deklaration nicht existieren würde. Im folgenden Beispiel sehen wir, was passiert, wenn eine reguläre CSS-Deklaration ungültig ist; color: 16px; wird verworfen und die vorherige color: blue-Regel wird stattdessen angewendet:

<p>This paragraph is initially black.</p>

p {
  font-weight: bold;
  color: blue;
}

p {
  /* oops, not a valid color */
  color: 16px;
}

Wenn die Werte benutzerdefinierter Eigenschaften geparst werden, weiß der Browser jedoch noch nicht, wo sie verwendet werden, daher muss er fast alle Werte als gültig ansehen. Leider können diese gültigen Werte über die var()-Funktionsnotation in einem Kontext verwendet werden, in dem sie möglicherweise keinen Sinn ergeben. Eigenschaften und benutzerdefinierte Variablen können zu ungültigen CSS-Anweisungen führen, was zum Konzept des gültigen Wertes zur berechneten Zeit führt.

Wenn der Browser auf eine ungültige var()-Ersetzung stößt, wird der anfängliche oder geerbte Wert der Eigenschaft verwendet. Dieses Beispiel ist ähnlich wie das letzte, außer dass wir eine benutzerdefinierte Eigenschaft verwenden.

Der Browser ersetzt den Wert von --text-color durch var(--text-color), aber 16px ist kein gültiger Eigenschaftswert für color. Nach der Ersetzung macht die Eigenschaft keinen Sinn, weshalb der Browser diese Situation in zwei Schritten handhabt:

1. Überprüfen Sie, ob die Eigenschaft color vererbbar ist. Sie ist es, aber dieses <p> hat kein Elternteil mit gesetzter color-Eigenschaft. Also gehen wir zu Schritt zwei über.
2. Setzen Sie den Wert auf seinen Standardanfangswert, der schwarz ist.

<p>This paragraph is initially black.</p>

:root {
  --text-color: 16px;
}

p {
  font-weight: bold;
  color: blue;
}

p {
  color: var(--text-color);
}

In solchen Fällen kann die @property-At-Regel unerwartete Ergebnisse verhindern, indem Sie den Anfangswert der Eigenschaft definieren:

<p>This paragraph is initially black.</p>

@property --text-color {
  syntax: "<color>";
  inherits: false;
  initial-value: teal;
}

:root {
  --text-color: 16px;
}

p {
  font-weight: bold;
  color: blue;
}

p {
  color: var(--text-color);
}

Werte in JavaScript

Um die Werte von benutzerdefinierten Eigenschaften in JavaScript zu verwenden, geschieht dies wie bei Standard-Eigenschaften.

// get variable from inline style
element.style.getPropertyValue("--my-var");

// get variable from wherever
getComputedStyle(element).getPropertyValue("--my-var");

// set variable on inline style
element.style.setProperty("--my-var", jsVar + 4);

Siehe auch

• @property-At-Regel
• var()
• CSS benutzerdefinierte Eigenschaften für kaskadierende Variablen Modul
• Syntax für benutzerdefinierte Eigenschaften
• CSS Properties and Values API