@property

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

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

syntax

Ein String, der die erlaubten Werttypen für die registrierte benutzerdefinierte Eigenschaft beschreibt. Kann ein Datentypname sein (wie <color>, <length> oder <number>, etc.), mit Multiplikatoren (+, #) und Kombinatoren (|), oder ein benutzerdefinierter Identifikator. Weitere Informationen finden Sie auf der Seite des syntax Deskriptors.

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 festlegt.

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

• Die @property-Regel muss sowohl den syntax als auch den inherits Deskriptor enthalten. Fehlt einer von beiden, 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 (d.h. syntax: "*"). Wenn der initial-value Deskriptor gefordert ist, aber weggelassen wird, ist die gesamte @property-Regel ungültig und wird ignoriert.
• Unbekannte Deskriptoren sind ungültig und werden ignoriert, machen jedoch die @property-Regel nicht ungültig.

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

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

<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 verwendet die CSS @property at-rule, um eine benutzerdefinierte Eigenschaft namens --item-size zu definieren. Die Eigenschaft setzt den Anfangswert auf 40% und beschränkt gültige Werte auf <percentage> Werte. Das bedeutet, dass, wenn diese Eigenschaft für die Größe eines Elements verwendet wird, ihre Größe immer relativ zur Größe des übergeordneten Elements ist. Die Eigenschaft ist vererbbar.

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

Wir definieren eine zweite benutzerdefinierte Eigenschaft, --item-color, mit JavaScript anstelle von CSS. Die JavaScript-Methode registerProperty() ist äquivalent zur @property at-rule. Die Eigenschaft wird definiert, um einen Anfangswert von aqua zu haben, akzeptiert nur <color> Werte und wird nicht vererbt.

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

Wir verwenden die zwei 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 beiden benutzerdefinierten Eigenschaften, --item-size: 20% und --item-color: orange; werden auf dem Elternteil container gesetzt und überschreiben die 40% und aqua Standardwerte, die beim Definieren dieser benutzerdefinierten Eigenschaften gesetzt wurden. Die Größe ist als vererbbar festgelegt, die Farbe nicht.

Für das erste Element sind keine dieser benutzerdefinierten Eigenschaften gesetzt. Die --item-size ist vererbbar, daher wird der Wert 20%, der auf seinem Elternteil container gesetzt wurde, verwendet. 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 Standardanfangswert aqua verwendet.

Für das zweite Element sind für beide benutzerdefinierten Eigenschaften CSS-Globalschlüsselwörter gesetzt, die gültige Werte für alle Werttypen sind und daher gültig sind, unabhängig vom Wert des syntax Deskriptors. Die --item-size ist auf initial gesetzt und verwendet den initial-value: 40%;, der in der @property Deklaration gesetzt wurde. 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 standardmäßig nicht vererbt wird. Deshalb ist das zweite Element orange.

Für das dritte Element wird der --item-size Wert auf 1000px gesetzt. Während 1000px ein <length> Wert ist, erfordert die @property Deklaration, dass der Wert ein <percentage> ist, sodass die Deklaration ungültig ist und ignoriert wird. Das bedeutet, dass der vererbbare 20%, der auf dem Elternteil gesetzt ist, verwendet wird. Der xyz Wert ist ebenfalls ungültig. Da registerProperty() --item-color auf nicht vererbbar gesetzt hat, wird der Standardanfangswert aqua verwendet und nicht der orange Wert des Elternteils.

• var()
• CSS Properties and Values API
• CSS Painting API
• CSS Typed Object Model
• Houdini APIs
• Using CSS custom properties (variables) Leitfaden
• CSS custom properties for cascading variables Modul