@property

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

Der Name der benutzerdefinierten Eigenschaft ist ein <dashed-ident>, der mit -- beginnt und auf einen gültigen, benutzerdefinierten Bezeichner folgt. Es wird zwischen Groß- und Kleinschreibung unterschieden.

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 zum Syntax-Deskriptor.

inherits

Ein boolescher Wert, der steuert, ob die von @property spezifizierte Benutzereigistrierung standardmäßig vererbbar ist.

initial-value

Ein Wert, der den Anfangswert 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. 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 (d.h. syntax: "*"). Wenn der initial-value-Deskriptor erforderlich, aber weggelassen wird, 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 rechnerisch unabhängigen Wert haben. Das bedeutet, dass der Wert in einen berechneten Wert umgewandelt werden kann, ohne von anderen Werten abhängig zu sein, außer von "globalen" Definitionen, die unabhängig von CSS sind. Zum Beispiel ist 10px rechnerisch unabhängig – es ändert sich nicht, wenn es in einen berechneten Wert umgewandelt wird. 2in ist auch gültig, da 1in immer 96px entspricht. 3em ist jedoch nicht gültig, da der Wert eines em von der font-size des übergeordneten Elements abhängt.
• Unbekannte Deskriptoren sind ungültig und werden ignoriert, machen aber 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 verwenden, um die Größe (Breite und Höhe) und die Hintergrundfarbe der folgenden drei 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 verwendet die CSS-@property-At-Regel, um eine benutzerdefinierte Eigenschaft namens --item-size zu definieren. Die Eigenschaft legt den Anfangswert auf 40% fest und beschränkt gültige Werte auf prozent-Werte. Das bedeutet, dass sie bei Verwendung als Wert für die Größe eines Elements immer relativ zur Größe seines Elternelements sein wird. Die Eigenschaft ist vererbbar.

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

Wir definieren eine zweite benutzerdefinierte Eigenschaft, --item-color, unter Verwendung von JavaScript statt CSS. Die JavaScript-Methode registerProperty() ist äquivalent zur @property-At-Regel. Die Eigenschaft wird so definiert, dass sie einen Anfangswert von aqua hat, nur <color>-Werte akzeptiert und nicht vererbart 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 beiden benutzerdefinierten Eigenschaften, --item-size: 20% und --item-color: orange;, werden auf dem übergeordneten container festgelegt und überschreiben die Standardwerte 40% und aqua, die bei der Definition dieser benutzerdefinierten Eigenschaften festgelegt wurden. Die Größe ist vererbbar; die Farbe nicht.

Für das erste Element wurden keine dieser benutzerdefinierten Eigenschaften festgelegt. Die --item-size ist vererbbar, sodass der auf ihrem Elternteil container festgelegte Wert 20% verwendet wird. Andererseits ist die Eigenschaft --item-color nicht vererbbar, sodass der auf dem Elternteil festgelegte Wert orange nicht berücksichtigt wird. Stattdessen wird der Standard-Anfangswert aqua verwendet.

Für das zweite Element sind CSS-Globale Schlüsselwörter für beide benutzerdefinierten Eigenschaften festgelegt, die gültige Werte für alle Werttypen sind und daher unabhängig vom Wert des syntax-Deskriptors gültig. Die --item-size ist auf initial gesetzt und verwendet den initial-value: 40%;, der in der @property-Deklaration festgelegt ist. Der Wert initial bedeutet, dass der initialValue-Wert der Eigenschaft verwendet wird. Die --item-color ist auf inherit gesetzt und erbt explizit den orange Wert von ihrem Elternteil, obwohl die benutzerdefinierte Eigenschaft so eingestellt ist, dass sie ansonsten 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 Länge-Wert ist, verlangt die @property-Deklaration, dass der Wert ein <percentage> ist, sodass die Deklaration ungültig ist und ignoriert wird, was bedeutet, dass das vererbliche 20%, das auf dem Elternteil festgelegt ist, verwendet wird. Der xyz-Wert ist ebenfalls ungültig. Da registerProperty() --item-color nicht vererbbar gesetzt hat, wird der Standard-Anfangswert aqua verwendet und nicht der orange-Wert des Elternteils.

In diesem Beispiel definieren wir eine benutzerdefinierte Eigenschaft namens --progress mit @property: diese akzeptiert <percentage>-Werte und hat einen Anfangswert von 25%. Wir verwenden --progress, um die Positionswerte der Farbabschnitte in einem linear-gradient() festzulegen, bei dem eine grüne Farbe aufhört und schwarz beginnt. Anschließend animieren wir den Wert von --progress zu 100% über 2,5 Sekunden, was den Effekt hat, eine Fortschrittsbalken-Animation zu erzeugen.

<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),
    #000000 var(--progress)
  );
  animation: progressAnimation 2.5s ease infinite;
}

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

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