@property

Syntax

@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-sensitiv.

Deskriptoren

syntax

Ein String, der die erlaubten Wertetypen für die registrierte benutzerdefinierte Eigenschaft beschreibt. Kann ein Datentyp-Name (wie <color>, <length> oder <number>, etc.) sein, mit Multiplikatoren (+, #) und Kombinatoren (|) oder ein benutzerdefinierter Identifikator. Details siehe die Beschreibung des Syntax-Deskriptors.

inherits

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

initial-value

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

Beschreibung

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 davon 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 unabhängig berechenbaren Wert haben. Dies bedeutet, dass der Wert in einen berechneten Wert umgewandelt werden kann, ohne von anderen Werten abzuhängen, mit Ausnahme von "globalen" Definitionen, die unabhängig von CSS sind. Zum Beispiel ist 10px unabhängig berechenbar—es ändert sich nicht, wenn es in einen berechneten Wert umgewandelt wird. 2in ist auch gültig, weil 1in immer 96px entspricht. 3em ist jedoch nicht gültig, weil der Wert eines em von der font-size des Elternteils abhängig ist.
• Unbekannte Deskriptoren sind ungültig und werden ignoriert, aber sie machen die @property-Regel nicht ungültig.

Formale Syntax

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

Beispiele

Verwendung von @property, um eine benutzerdefinierte Eigenschaft zu registrieren und zu verwenden

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 verwendet die CSS-@property-At-Regel, um eine benutzerdefinierte Eigenschaft mit dem Namen --item-size zu definieren. Die Eigenschaft legt den Anfangswert auf 40% fest und beschränkt gültige Werte nur auf <percentage>-Werte. Das bedeutet, dass die Größe eines Elements, wenn es als Wert verwendet wird, immer relativ zur Größe des Elternelements 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 gleichwertig zur @property-At-Regel. Die Eigenschaft wird 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 beiden benutzerdefinierten Eigenschaften --item-size: 20% und --item-color: orange; werden auf dem übergeordneten container-Element gesetzt und überschreiben die 40% und aqua Standardwerte, die definiert wurden, als diese benutzerdefinierten Eigenschaften festgelegt wurden. Die Größe ist vererbbar; die Farbe jedoch nicht.

Für das erste Element wurden keine dieser benutzerdefinierten Eigenschaften gesetzt. Die --item-size ist vererbbar, daher wird der auf dem Eltern-container gesetzte Wert 20% verwendet. Die Eigenschaft --item-color ist hingegen nicht vererbbar, daher wird der auf dem Eltern gesetzte Wert orange nicht berücksichtigt. Stattdessen wird der Standardanfangswert aqua verwendet.

Für das zweite Element werden für beide benutzerdefinierten Eigenschaften CSS-Globale Schlüsselwörter gesetzt, die gültige Werte für alle Wertetypen sind und daher unabhängig vom Wert des syntax-Deskriptors gültig sind. Die --item-size ist auf initial gesetzt und verwendet den initial-value: 40%;, der in der @property-Deklaration festgelegt 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 Eltern, obwohl die benutzerdefinierte Eigenschaft so gesetzt ist, dass sie sonst nicht vererbt wird. Daher 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, daher ist die Deklaration ungültig und wird ignoriert, was bedeutet, dass das vererbbare 20%, das auf dem Eltern gesetzt ist, verwendet wird. Der xyz-Wert ist ebenfalls ungültig. Da registerProperty() --item-color auf nicht vererbbar gesetzt hat, wird der Standardanfangswert von aqua verwendet und nicht der orange-Wert des Eltern.

Animieren eines benutzerdefinierten Eigenschaftswertes

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 zur Definition des Positionswertes der Farbstops in einem linear-gradient(), der angibt, wo eine grüne Farbe endet und schwarz beginnt. Wir animieren dann den Wert von --progress auf 100% über 2,5 Sekunden, was den Effekt eines animierten Fortschrittsbalkens gibt.

<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 CSS-Benutzereigenschaften (Variablen) Leitfaden
• CSS-Benutzereigenschaften für kaskadierende Variablen Modul