@property

Syntax

@property --rotation {
  syntax: "<angle>";
  inherits: false;
  initial-value: 45deg;
}

Der Name der benutzerdefinierten Eigenschaft ist ein <dashed-ident>, der mit -- beginnt und von einem gültigen, benutzerdefinierten Bezeichner gefolgt wird. Er ist case-sensitiv.

Deskriptoren

syntax

Ein String, der die erlaubten Wertetypen für die registrierte benutzerdefinierte Eigenschaft beschreibt. Kann ein Datentypname (wie <color>, <length> oder <number>, etc.) sein, mit Multiplikatoren (+, #) und Kombinatoren (|), oder ein benutzerdefinierter Identifikator. Siehe die syntax Deskriptor-Seite für weitere Details.

inherits

Ein boolescher Wert, der steuert, ob die von @property spezifizierte benutzerdefinierte Eigenschaft standardmäßig vererbt wird.

initial-value

Ein Wert, der den Startwert für die Eigenschaft setzt.

Beschreibung

Die folgenden Bedingungen müssen erfüllt sein, damit die Regel @property gültig ist:

• Die @property-Regel muss sowohl den syntax als auch den inherits Deskriptor enthalten. Wenn einer von beiden fehlt, ist die gesamte @property-Regel ungültig und wird ignoriert.
• Der initial-value Deskriptor ist optional, wenn der Wert des syntax-Deskriptors die universelle Syntaxdefinition ist (also syntax: "*"). Wenn der initial-value-Deskriptor erforderlich ist, aber fehlt, ist die gesamte @property-Regel ungültig und wird ignoriert.
• Wenn der Wert des syntax-Deskriptors nicht die universelle Syntaxdefinition ist, muss der initial-value Deskriptor einen rechentechnisch unabhängigen Wert haben. Das bedeutet, der Wert kann in einen berechneten Wert umgewandelt werden, ohne von anderen Werten abhängig zu sein, außer für "globale" Definitionen, die unabhängig von CSS sind. Zum Beispiel ist 10px rechentechnisch unabhängig — es ändert sich nicht, wenn es in einen berechneten Wert umgewandelt wird. 2in ist auch gültig, da 1in immer gleich 96px ist. Allerdings ist 3em nicht gültig, da der Wert eines em von der font-size des Elternteils abhängt.
• Unbekannte Deskriptoren sind ungültig und werden ignoriert, machen die @property-Regel jedoch nicht ungültig.

Formale Syntax

@property = 
  @property <custom-property-name> { <declaration-list> }  

Beispiele

Verwendung von @property zur Registrierung und Nutzung einer benutzerdefinierten Eigenschaft

In diesem Beispiel definieren wir zwei benutzerdefinierte Eigenschaften, --item-size und --item-color, die wir verwenden, um die Größe (Breite und Höhe) und die Hintergrundfarbe der drei folgenden Elemente zu definieren.

<div class="container">
  <div class="item one">Item one</div>
  <div class="item two">Item two</div>
  <div class="item three">Item three</div>
</div>

Der folgende Code nutzt die CSS-At-Regel @property, um eine benutzerdefinierte Eigenschaft namens --item-size zu definieren. Die Eigenschaft setzt den Anfangswert auf 40% und beschränkt die gültigen Werte auf <percentage>-Werte. Das bedeutet, dass bei Verwendung als Wert für die Größe eines Elements seine Größe immer relativ zur Größe des Elternteils sein wird. Die Eigenschaft ist vererbbar.

@property --item-size {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 40%;
}

Wir definieren eine zweite benutzerdefinierte Eigenschaft, --item-color, mithilfe von JavaScript anstelle von CSS. Die JavaScript-Methode registerProperty() ist der At-Regel @property gleichwertig. Die Eigenschaft ist so definiert, dass sie einen Anfangswert von aqua hat, nur <color>-Werte akzeptiert und nicht vererbt wird.

window.CSS.registerProperty({
  name: "--item-color",
  syntax: "<color>",
  inherits: false,
  initialValue: "aqua",
});

Wir verwenden die beiden benutzerdefinierten Eigenschaften, um die Elemente zu stylen:

.container {
  display: flex;
  height: 200px;
  border: 1px dashed black;

  /* set custom property values on parent */
  --item-size: 20%;
  --item-color: orange;
}

/* use custom properties to set item size and background color */
.item {
  width: var(--item-size);
  height: var(--item-size);
  background-color: var(--item-color);
}

/* set custom property values on element itself */
.two {
  --item-size: initial;
  --item-color: inherit;
}

.three {
  /* invalid values */
  --item-size: 1000px;
  --item-color: xyz;
}

Die zwei benutzerdefinierten Eigenschaften, --item-size: 20% und --item-color: orange; werden auf dem Elternelement container gesetzt und überschreiben die 40% und aqua Standardwerte, die beim Definieren dieser benutzerdefinierten Eigenschaften festgelegt wurden. Die Größe ist als vererbbar festgelegt; die Farbe ist es nicht.

Für Element eins wurden keine dieser benutzerdefinierten Eigenschaften gesetzt. Die --item-size ist vererbbar, sodass der Wert 20%, der auf seinem Eltern-container gesetzt ist, verwendet wird. Andererseits ist die Eigenschaft --item-color nicht vererbbar, sodass der Wert orange, der auf dem Elternteil gesetzt ist, nicht berücksichtigt wird. Stattdessen wird der anfängliche Standardwert aqua verwendet.

Für Element zwei sind globale CSS-Schlüsselwörter für beide benutzerdefinierten Eigenschaften gesetzt, die gültige Werte für alle Wertesätze sind und deshalb unabhängig vom syntax-Deskriptorwert gültig sind. Die --item-size ist auf initial gesetzt und verwendet den in der @property-Deklaration gesetzten initial-value: 40%;. Der initial-Wert bedeutet, dass der initialValue-Wert für die Eigenschaft verwendet wird. Die --item-color ist auf inherit gesetzt und erbt explizit den orange-Wert von ihrem Elternteil, obwohl die benutzerdefinierte Eigenschaft ansonsten so eingestellt ist, dass sie nicht vererbbar ist. Deshalb ist Element zwei orange.

Für Element drei wird der --item-size-Wert auf 1000px gesetzt. Obwohl 1000px ein <length>-Wert ist, erfordert die @property-Deklaration, dass der Wert ein <percentage>-Wert ist, sodass die Deklaration ungültig ist und ignoriert wird, was bedeutet, dass die vererbbare 20%, die auf den Eltern gesetzt ist, verwendet wird. Der xyz-Wert ist ebenfalls ungültig. Da registerProperty() --item-color so eingestellt hat, dass es nicht vererbt wird, wird der Standard-Anfangswert aqua verwendet und nicht der orange-Wert des Elternteils.

Animieren eines benutzerdefinierten Eigenschaftswerts

In diesem Beispiel definieren wir eine benutzerdefinierte Eigenschaft namens --progress mit @property: sie akzeptiert <percentage>-Werte und hat einen Anfangswert von 25%. Wir verwenden --progress, um den Positionswert der Farbstopps in einem linear-gradient() zu definieren, der angibt, wo eine grüne Farbe endet und schwarz beginnt. Wir animieren dann den Wert von --progress zu 100% über 2,5 Sekunden, was den Effekt einer animierten Fortschrittsleiste ergibt.

<div class="bar"></div>

@property --progress {
  syntax: "<percentage>";
  inherits: false;
  initial-value: 25%;
}

.bar {
  display: inline-block;
  --progress: 25%;
  width: 100%;
  height: 5px;
  background: linear-gradient(
    to right,
    #00d230 var(--progress),
    black var(--progress)
  );
  animation: progressAnimation 2.5s ease infinite;
}

@keyframes progressAnimation {
  to {
    --progress: 100%;
  }
}

Spezifikationen

Browser-Kompatibilität

Siehe auch

• var()
• CSS Properties and Values API
• CSS Painting API
• CSS Typed Object Model
• Houdini APIs
• Verwendung von benutzerdefinierten CSS-Eigenschaften (Variablen) Leitfaden
• CSS-Benutzerdefinierte Eigenschaften für kaskadierende Variablen Modul